Tricks of the Mac Game Programming Gurus/TricksOfTheMacGameProgrammingGurus.iso/More Source/C⁄C++/Xconq 7.0d37/doc/refman.texi

Texinfo Document | 1995-05-04 | 189KB | 4,471 lines

@node Reference Manual,,,
@chapter Reference Manual
This manual is the complete description of GDL.
The style is somewhat terse; for more detail on how to
use GDL to design games, see Chapter 3.
Please note that the current version of Xconq may not fully
implement all of the constructs or combinations of constructs
described here.  Any such omissions should be regarded as bugs.
@section Language Syntax
GDL resembles Lisp, but instead of defining functions,
the contents of a file declare
certain objects (such as units and unit types) to exist,
and specify values for their properties.
In other words, GDL is @emph{nonprocedural}.
This means that most of the time, you can list the various
forms in any order you like.
The main restriction is that any symbol, such as a variable
or the name of a type, must be defined before it is used.
Also, forms such as @code{set} and @code{add}, that set the
value of a variable or property,
always overwrite the previous data irreversibly,
so ordering of these is very important.
@subsection Lexical Elements
Numbers are introduced by a decimal digit, plus, or minus signs.
They may contain only decimal digits, a decimal point, and be followed
(immediately, no whitespace allowed)
by a percent sign or a recognized unit of measure.
Strings are sequences of characters enclosed by doublequotes (@code{"}).
They may contain any character except ASCII NUL (@code{'\0'}).
To include a doublequote, use backslash, as in @code{"a \"quoted\" string"}.
To include a nonprinting or eight-bit character,
use backslash followed by three octal
digits, which will be interpreted as an eight-bit character code.
(This is mostly the same syntax as in C.)
Note that game design files may be passed over networks
and between different kinds of computer systems,
so non-ASCII characters should not be inserted verbatim into strings.
Symbols are sequences of characters that don't
include any of the other special characters.  If you wish to include such
characters in a symbol, enclose it in vertical bars,
for example @code{|foo bar|}.
(The bars are not part of the symbol.)
Symbols are case-sensitive,
but this will be changed eventually.
Lists are a sequence of expressions enclosed in parentheses.
The empty list is either @code{nil} or @code{()}.
``Dotted pairs'' are not allowed.
Anything that is not a list is an @dfn{atom}.
All of these objects may range up to a very large size.
(You may still run into bugs if you make strings or symbols
over about 100 chars in length.)
Comments are enclosed either within @code{#| |#} (which nests properly,
like Common Lisp and unlike C), or else extend from a semicolon
@code{;} to the end of the line.  A comment is equivalent to whitespace,
so @code{(a#|bcd|#e)} is the same as @code{(a e)}, not @code{(ae)}.
@code{#} by itself is a normal token.
True/false values
are just the integers 0 and 1, with no special characteristics.
@deffn GlobalConstant @code{true}
@end deffn
@deffn GlobalConstant @code{false}
These constants are symbolic forms for @code{1} and @code{0}.
They are identical to numbers,
but more descriptive for parameters that are boolean-valued.
@end deffn
Unit, material, and terrain types are distinct objects.
However, they can be considered to have numeric ``indices''
assigned in order of the types' definition.  These numbers
are not directly visible in GDL, but they often affect sorting
and ordering.
@subsection Conventions Used
Descriptions of values in this manual follow the conventions listed here.
For parameters described as @var{t/f},
both @code{1}, @code{0} and @code{true}, @code{false} may be used.
Parameters described as @var{n} and @var{n%} are numbers.
Parameters described as @var{dist} or @var{length}
are also numbers, but are in the unit of measure for lengths.
Parameters described as @var{str} or @var{string} are strings.
Parameters described as
@var{u} or @var{ui}, @var{m} or @var{mi}, and @var{t} or @var{ti},
are values that must be unit, material, or terrain types, respectively.
Parameters described as @var{utype-value-list} match unit types with values.
They can have several forms:
@itemize
@item
@code{(n1 n2 ...)} matches @code{n1} with type 0, etc in order.
@item
@code{((u1 n1) (u2 n2) ...)} evaluates @code{u1} to get a unit type,
then matches it with @code{n1}.  @code{u1} etc may also be a list of
types, in which case all the types get matched with @code{n1}.
@end itemize
Other types of lists, such as those defined as @var{side-value-list},
are interpreted similarly.  For all of these, multiple assignments to
the same type etc will overwrite quietly.
@subsection Forms and Evaluation
A @dfn{form} is either any single expression that appears in the file.
A GDL file consists of a sequence of forms.
Most forms of interest will be lists
whose first element is a symbol identifying the form.
For instance, a form beginning with the symbol @code{side}
declares a side object.
When the file containing such a form is read, @i{Xconq} will
create a side object and fill in any properties as specified by the form.
(Properties are like properties or attributes - most GDL objects
have some.)
In most contexts, @i{Xconq} will @dfn{evaluate} an expression
before using it, such as when filling in an object's property.
Numbers and strings evaluate to themselves, while symbols
evaluate to their bindings, as set by @code{set} or @code{define}.
Lists evaluate to a list of the same length, but with all the elements
evaluated, unless the first element of the list is a function.
In that case,
the remaining elements of the list are evaluated and given to the
function, and its result will be the result.
@subsection Tables
A @dfn{table} is a two-dimensional array of values indexed by types.
Indices can be any pair of unit, material, or terrain type.
The set of tables is fixed by @i{Xconq}, and all are described below.
@deffn Form @code{table} table-name items@dots{}
This is the general form to fill in a table.
The table named by @var{table-name} is filled in from the @var{items}.
If an item is an atom, then every position in the
table is filled in with that item, overwriting any
previously-specified values.
If an item is a list, it must be a three-element list
of the form @code{(@var{type1} @var{type2} @var{value})}.
If both @var{type1} and @var{type2} are single types,
then @var{value} will be put into the table at the position
indexed by the two types.
If one of @var{type1} or @var{type2} evaluates to a list,
@i{Xconq} will iterate over all members of the list while
keeping the other type constant,
while if both @var{type1} and @var{type2} are lists,
then @i{Xconq} will iterate over all pairs from the two lists.
The values used during iteration depend on whether the @var{value}
is a list.  If @var{value} is an atom, then that value will just
be used on every iteration.  If a list, then @i{Xconq} will
use successive elements of the list while iterating.
If the first member of @var{items} is the symbol @code{add},
then the rest of the items will add to the existing contents
of the table rather than clearing to its default value first.
@end deffn
The following forms are all equivalent:
@example
(table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9))
(table foo ((a b c) y (1 2 3)) ((a b c) (z) 9))
(define v1 (a b c))
(table foo (v1 y (1 2 3)) (v1 z 9))
(table foo ((a b c) (y z) ((1 2 3) (9 9 9))))
(table foo (a y 1) (b y 2) (c y 3))
(table foo add ((a b c) z 9))
@end example
@subsection Modifying Objects
Since forms normally define or create new objects,
GDL defines the @code{add} form to modify existing objects.
@deffn Form @code{add} objects property new-values@dots{}
This form evaluates the atom or list @var{objects} to arrive at the
set of objects to be modified.
Then it uses the @var{new-values} to write new data into
the property named @var{property} of those objects.
The @var{new-values} may be a single number or string, or a list.
@end deffn
@subsection Symbols
Most of the symbols used in a game module are the predefined ones
described in this manual.
Others are attached to types when the types are defined,
and still others name objects like units and sides.
You can also define and set your own symbols to arbitrary values.
@deffn Form @code{define} symbol value
This form defines the symbol @var{symbol} to be bound to the
result of evaluating @var{value}.
If @var{symbol} is already defined, @i{Xconq} will issue a warning,
and ignore this form.
@end deffn
@deffn Form @code{set} symbol value
This form rebinds the already-bound symbol @var{symbol}
to be bound to the result of evaluating @var{value}.
If @var{symbol} is @emph{not} bound already,
then @i{Xconq} will issue a warning, but proceed anyway.
@end deffn
@deffn Form @code{undefine} symbol
This form destroys any binding of the @var{symbol}.
This is allowed for any symbol, including already-unbound symbols.
@end deffn
@subsection Lists
@deffn Function @code{quote} xxx@dots{}
This function prevents any evaluation of @var{xxx}.
(This implies that the abovementioned evaluation of the argument
list does @i{not} happen for this ``function''.)
@end deffn
@deffn Function @code{list} xxx@dots{}
This function makes a list out of all the @var{xxx}.
@end deffn
@deffn Function @code{append} xxx@dots{}
This function appends all the @var{xxx} (which may be
lists or not) into a single list.  Non-lists will appear
as though they were single-element lists.
@end deffn
@deffn Function @code{remove} list1 list2
This function removes the members of @var{list1} from @var{list2},
returning the result.
@end deffn
@section Game Modules
The game module declaration supplies information about the file as a whole.
It is optional; if missing, @i{Xconq} will get the module's
name from its file name, and supply defaults for the other properties.
@deffn Form @code{game-module} [name] properties@dots{}
This form defines the properties of this game module.
The optional @var{name} is a string that will be used to look up
the module in libraries.
If the @var{name} is supplied, then this form is considered to be the
definition of the module, and overwrites any
@code{game-module} form previously appearing in this file.
If @var{name} is missing, then this form will modify the
existing description of the module.
@end deffn
@deffn ModuleProperty @code{title} string
If defined, this property is the name by which the module will be displayed to
players.  It is not used internally, so the name can be modified freely
(unlike the module's name, which may appear in other modules).
Defaults to the module's name.
@end deffn
@deffn ModuleProperty @code{blurb} string
This property is a one-line description that users will see when they
are deciding whether to play the module.
It will be displayed without any modification:
@example
Welcome to my nightmare! (version 1.0 with stronger goblins)
@end example
Defaults to @code{""}.
@end deffn
@deffn ModuleProperty @code{picture-name} string
This property is the name of a picture that may be displayed along
with the module's blurb, by those interfaces that support such pictures.
Defaults to @code{""}.
@end deffn
@deffn ModuleProperty @code{base-game} t/f
@end deffn
@deffn ModuleProperty @code{instructions} strings@dots{}
This property is a list of strings that are the instructions on how to play
the game.  Defaults to @code{()}.
@end deffn
@deffn ModuleProperty @code{notes} strings@dots{}
This property is a list of strings comprising the set of
detailed player's notes for the module.
Both the list and each string in the list can be of any length.
When displayed, the strings are all concatenated together, so the division
into strings here is just for convenience.
How these are displayed is up to the interface, but in general an empty
string signals a new paragraph.
Defaults to @code{()}.
@end deffn
@deffn ModuleProperty @code{design-notes} strings@dots{}
This property is a list of strings that are notes addressed to game designers.
Defaults to @code{()}.
@end deffn
@deffn ModuleProperty @code{version} string
This property is the version of the module.
Defaults to @code{""},
which indicates that the module's version is undefined.
@end deffn
@deffn ModuleProperty @code{program-version} versions
This property dentifies @i{Xconq} versions for which this module
is appropriate.
If specified, then players will get a warning if they attempt to use this
module with an inappropriate version of @i{Xconq}.
Possible forms include a string, which allows the module only for
exactly matching version of @i{Xconq},
and @code{(@var{comparison} @var{version})},
which allows versions satisfying the @var{comparison} test,
which may only be @code{>=} or @code{<=}.
So for instance
@example
(game-module "foo" (program-version (>= "7.0.3")))
@end example
is claimed to only work for versions 7.0.3 or later.
Defaults to @code{""}, which means that the module is appropriate for
any version of @i{Xconq}.
Notes that the @code{program-version} is strictly a heuristic to forewarn
players; in practice it can be very difficult to know which modules work
with which programs.  (The problems are similar to those encountered
by programmers using different compiler versions on their programs.)
@end deffn
@deffn ModuleProperty @code{base-module} name
This property is the name of a module that must be loaded first.
It is similar in effect to @code{include}.
@end deffn
@deffn ModuleProperty @code{default-base-module} name
This property specifies the name of a module that will be loaded
if this module is given as the ``top-level'' module,
such as via @code{-g} on a command line.
This is to prevent disasters when a library module that is
used only by other modules is instead loaded as if it were
a full game design.
@end deffn
@subsection Variants
Variants are options chosen by players at the start of a game.
A generic variant includes information that will be used for displaying
the choice to players, the acceptable range of choices, a default
choice, and additional forms that may be evaluated if particular
values were chosen.  Variant values are always numbers.
@deffn ModuleProperty @code{variants} items@dots{}
This property defines named variants on this module.
Variants appear as startup options for the game.
The items have the form
@code{([@var{name}] @var{type} [@var{range/default}] [@var{clauses}])}.
The @var{name} is a string or symbol used to identify the choice to
the players, the @var{type} says what sort of change is being enabled,
@var{range/default} supplies a range of values and a default value
among them,
and @var{clauses} is a list of the form @code{(@var{value} @var{forms}@dots)}.
A game module may specify any number of variants.
Defaults to @code{()}.
@end deffn
A number of commonly useful variant types are predefined.
@deffn VariantType @code{world-size} [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]
This variant allows players to choose the size of the world.
The sizes will default to the values in this variant's data.
(@var{width} and @var{height} can be lists of the form @code{(lo dflt hi)},
with the obvious interpretation??)
@end deffn
@deffn VariantType @code{world-seen} [ dflt ] [ clauses ]
This variant allows players to choose whether
the terrain of the world will be known at the start of the game.
The default setting will be the value @code{dflt},
which may be either @code{true} or @code{false}.
@end deffn
@deffn VariantType @code{see-all} [ dflt ] [ clauses ]
This variant allows players to choose whether everything will be seen
always, as with the global variable @code{see-all}.
The default is set by @code{dflt}.
@end deffn
@deffn VariantType @code{sequential} [ dflt ] [ clauses ]
This variant allows players to choose whether to move
simultaneously during a turn, or one at a time.
The default is set by @var{dflt}.
@end deffn
@deffn VariantType @code{real-time} [ total [ perside [ perturn ] ] ] [ clauses ]
This variant allows players to choose realtime limits on the game.
The value will default to the values in this variant's data.
@c but what about upper/lower limits?
@end deffn
@subsection Including Other Modules
You can include one game module in another.
@deffn Form @code{include} [if-needed] module-name [variant-settings]
This form has the effect of inserting the contents
of @var{module-name} into the current position in the module.
@code{game-module} forms in the included module are not inserted,
although they are remembered and may appear in displays.
@i{Xconq} will fail completely if the included module cannot be found.
Unlike C etc, the same module cannot be included more than once; you will
get a warning and the module will not be loaded.
@end deffn
Note that the module names are not file names,
so that system-specific features like directories and devices
cannot be included.
The mapping between module name and file name is interface-specific,
so if you want to distribute a module, you should make sure all the
module names don't have anything nonportable embedded.
Alphanumeric characters and hyphens are guaranteed to be portable.
@subsection Conditional Loading
You can control which forms in a module are actually evaluated
by using conditional loading.
@deffn Form @code{if} test-form sym
@end deffn
@deffn Form @code{else} sym
@end deffn
@deffn Form @code{end-if} sym
If @var{test-form} evaluates to @code{true},
then all subsequent forms, up until the matching @code{else}
or @code{end-if}, will be evaluated.
If @code{false}, then the forms will be read but not evaluated.
All forms inside the conditional must be syntactically correct.
@end deffn
@node World Design, Distances and Elevations, Language, Game Design
@section The World
The world consists of one @dfn{area},
which is regular in shape and consists of a number of @dfn{cells}.
Each cell has a type of terrain and a number of optional data values.
Each kind of per-cell data will be called a @dfn{layer} of the area.
@deffn Form @code{world} [ circumference ] properties@dots{}
This form defines the properties of the world as a whole.
@end deffn
@deffn WorldProperty @code{circumference} dist
This property is the distance around the entire world (as a sphere).
Default is @code{360}.
@end deffn
@deffn WorldProperty @code{axial-tilt} n
This property defines the extremes of seasonal changes.
@end deffn
@deffn Form @code{area} [ width [ height ] ] [ restriction ] properties@dots{}
This form defines the playing area of the world.
The @var{restriction} identifies how to get data for this area from
subsequent forms that are based on larger areas.
@end deffn
@deffn AreaRestriction @code{restrict} w h x y
This is a special form that specifies that subsequent layers in an
area of size w x h will be offset by x,y and then read into the
actual area.  (This is useful for setting up a game that needs
only a subset of a full map.)
Note that an area restriction is not a property, and must
always appear before any properties in an area form.
@end deffn
@deffn AreaProperty @code{width} n
@end deffn
@deffn AreaProperty @code{height} n
These properties are the width and height of the world,
as measured in cells.
Allowable values range from 3x3
up to 32767x32767, which is one billion cells!
If only one of these is given, then the other defaults to the same value.
If neither has been given, then they default to @code{60} and @code{30},
respectively.
@end deffn
In the case of a cylinder, the world wraps around
in the x direction, and the width is the diameter of the cylinder,
while the height is just the
height in the usual sense.
A hexagon world is flat on the top and bottom; its width is
measured across the middle height, which is the largest span,
and height is the same
as for cylinders.  Here are some crude pictures, first of an 8x6 cylinder:
@example
# # # # # # # #
 : : + + : : : :
: : : + ^ : : :
 : : : : : : : :
: : : : ^ : : :
 # # # # # # # #
@end example
This world is an 8x7 hexagon:
@example
   # # # # #
  # : + + : #
 # : : + ^ : #
# : : + ^ : : #
 # : : : : : #
  # : : ^ : #
   # # # # #
@end example
There are two kinds of properties that an area may have:
scalar values such as latitude,
and layer values such as terrain and elevation.
@deffn AreaProperty @code{latitude} n
This property is the offset, in cells, from the equator of the middle of the area
(height / 2).
Defaults to @code{0}.
@end deffn
@deffn AreaProperty @code{longitude} n
This property is the offset, in cells, from the ``Greenwich Meridian''
of the world.
Defaults to @code{0}.
@end deffn
@subsection Layers
@dfn{Layers} constitute the bulk of data about an area of the world.
Each layer assigns a value to each cell in the area;
examples include cell terrain, temperatures, elevations, and so forth.
Since there may be many cells in a layer with the same values,
each layer uses a common run-length encoding scheme.
In this scheme, each horizontal band of cells
is a separate text string, and the contents of the string encode
individual numeric values, one for each cell.
The encoding uses the characters @code{a..~} and @code{:..[}
for 0 through 63,
and decimal digits followed by commas (or the end of the string)
for all other numbers.
An optional @code{-} is allowed, and indicates a negative value.
Runs of constant value are prefixed with their length, in decimal.
The character @code{*} separates run lengths from values expressed
as digits.
Thus, the string
@example
"40adaa100,2*-99"
@end example
represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100,
and two -99s.
Although this format is quite unreadable,
it has the advantages of compactness and portability;
the expectation is that most layer editing will be done on-line.
Note that the run encoding is entirely optional.
The following subforms at the beginning of layer data have special effects:
@deffn LayerSubform @code{constant} n
This subform causes every value in the layer to be set to @var{n}.
@end deffn
@deffn LayerSubform @code{subarea} x y w h
This subform indicates that the layer data should be positioned at the given
rectangle in the layer.
@end deffn
@deffn LayerSubform @code{xform} mul add
This subform has the effect of first multiplying the raw value by @var{mul},
then adding @var{add} and storing the result into the layer.
@end deffn
@deffn LayerSubform @code{by-bits}
@end deffn
@deffn LayerSubform @code{by-char} str
This subform specifies that the characters in @var{str} give the
encodings of values in the layer.
The first character in @var{str} encodes 0, the second encodes 1,
and so forth.
@end deffn
@deffn LayerSubform @code{by-name} name-list
[what is the syntax of name-list exactly?]
This subform is for generic worlds that are useful across multiple game designs.
The value/name pairs allow for the matching of terrain types by name,
so that if, say,
the ``sea'' terrain type was type #0 in one game and type #4 in another,
the world would have sea in all the same places after it was read in.
In practice, only a few worlds are this general.
If a named terrain type is not present, @i{Xconq} will warn about it
and substitute type 0.
@end deffn
@deffn AreaProperty @code{terrain} layer-data@dots{}
This property is the actual layer of terrain types for cells.
@end deffn
@deffn AreaProperty @code{aux-terrain} terrain-type layer-data@dots{}
This property fills in values for borders, connections, and coatings.
For border and connection terrain,
the value is a six-bit number (0..63),
with a bit turned on in each direction that there is a border
or connection.
For coating types, the value is the depth of the coating.
@end deffn
@deffn AreaProperty @code{features} feature-list layer-data@dots{}
This property specifies the nature and location of all geographical features.
The @var{feature-list} is a list of lists, where each sublist has the form
@code{([@var{id}] @var{typename} @var{name} [@var{super}])}
where @var{id} is the numerical id referenced in the layer data
(defaults to feature's position in the @var{feature-list}),
@var{typename} is a symbol or string giving the general type of feature
(such as @code{bay}),
@var{name} is the name of the feature
(such as @code{"Bay of Bengal"}),
and @var{super} is the optional id of another feature that
incorporates this feature.
@end deffn
@deffn AreaProperty @code{material} material-type layer-data@dots{}
This property declares the quantity of the given @var{material-type}
in each cell of the area.
@end deffn
@deffn AreaProperty @code{people-sides} layer-data@dots{}
This property says which side the people of each cell are on.
A @var{side-encoding} of @code{exact} assigns 0 to independence (no side),
1 to the first side, and so forth; otherwise, the encoding is a list
of side names/ids and numbers.
@end deffn
@subsection Distances and Elevations
@deffn AreaProperty @code{elevations} layer-data@dots{}
This property is the world elevation data itself.
If any elevation falls outside the min/max elevation range
for the terrain type of the cell, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn
@deffn AreaProperty @code{cell-width} dist
This property is the distance across a single cell,
expressed as units of elevation.  Defaults to @code{1}.
@end deffn
@subsection Temperatures
Each type of terrain has a temperature range in which it may be found.
Any calculation that would fall outside this range will be clipped.
The temperature can be set to have a given value at a given elevation.
All air temperatures will be interpolated appropriately.
@deffn GlobalVariable @code{temperature-floor} n
This variable is the lowest possible temperature.
Defaults to @code{0}.
@end deffn
@deffn GlobalVariable @code{temperature-floor-elevation} n
This variable is the elevation at which the temperature is always at
@code{temperature-floor}.
Defaults to @code{0}.
@end deffn
@deffn AreaProperty @code{temperatures} layer-data@dots{}
This property contains the temperature data itself.
If any temperature falls outside the min/max temperature range, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn
@subsection Winds
Winds are defined as having a nonnegative force and a direction.
@deffn AreaProperty @code{winds} layer-data@dots{}
This property contains the force and direction of the prevailing
winds in each cell.
@end deffn
@subsection Clouds
Cloud cover is defined as a layer over the terrain, with
a bottom and top and density for each cell.
In the example below, @code{o} and @code{O} represent
different densities of cloud, and @code{-} show the tops
and bottoms, while @code{^} shows the ground.
@example
    ----     -
  --oOOo --  O
  OOoOOo oo--O
  --oOO- --OOO
    ---    ---
^^^^^^^^^^^^^^^^
@end example
@deffn AreaProperty @code{clouds} layer-data@dots{}
This property is the degree of cloud cover over each cell.
A value of @code{0} corresponds to clear skies.
@end deffn
@deffn AreaProperty @code{cloud-bottoms} layer-data@dots{}
This property is the altitude above the ground of the bottoms
of the clouds.
@end deffn
@deffn AreaProperty @code{cloud-heights} layer-data@dots{}
This property is the vertical thickness of the cloud cover
in each cell.
@end deffn
@section Sides
@deffn Form @code{side} [id] properties@dots{}
This form has the effect of declaring a side to exist.
If the number or symbol @var{id} is supplied and
matches that of a side that has already been created,
then the properties will modify the pre-existing side.
Otherwise a new side object will be created,
with a arbitrarily-chosen numeric id ranging between 1 and @code{sides-max}.
If the given @var{id} is a symbol, then the side's numeric id will be
bound to that symbol.
@end deffn
@deffn GlobalVariable @code{sides-min} n
@end deffn
@deffn GlobalVariable @code{sides-max} n
These variables are the minimum and maximum number of sides that may exist in
a game.  Defaults are to @code{1} and the internal parameter @code{MAXSIDES},
which is usually around 7.
@code{MAXSIDES} can only be changed by recompiling @i{Xconq}.
@end deffn
@deffn Form @code{side-defaults} properties@dots{}
This form sets the defaults for all newly-created sides declared
subsequently.
These defaults will be set before the new side's properties are interpreted.
This form has no effect on existing sides or on side declarations that
modify existing sides.
@end deffn
@subsection Name and Related Properties
If the game design allows, all of these properties can be set at startup by
the players (see <side config> and below).
Omission of some of these results in suppression or substitution,
depending on the interface and the situation.
Omission of all name properties allows the side to go unmentioned,
which is useful when the concept of ``side'' is useless or
confusing to a player (as in some adventure games).
All of these properties may be set at any time by any player.
@deffn SideProperty @code{name} str
This property is the proper name of a side, as a country or alliance name.
Examples include @code{"Axis"} and @code{"Hyperborea"}.
Defaults to @code{""}.
@end deffn
@deffn SideProperty @code{long-name} str
This property is the long form of a side's name,
as in @code{"People's Republic of Hyperborea"}.
Defaults to be the same as the side's name.
@end deffn
@deffn SideProperty @code{short-name} str
This property is an short name or acronym for the side,
often just the letters of the long name, as in @code{"PRH"}.
Defaults to @code{""}.
@end deffn
@deffn SideProperty @code{noun} str
This property is the name of an individual unit or person
belonging to the side.
Defaults to @code{""}, which suppresses any mention of the side
when (textually) describing the individual.
@end deffn
@deffn SideProperty @code{plural-noun} str
This property is what you would call a group of individuals.
Defaults to the most common plural form of the @code{noun}
(in English, the default pluralizer adds an ``s''),
so any alternative plural noun, such as @code{"Chinese"},
will need an explicit @code{plural-noun} value.
@end deffn
@deffn SideProperty @code{adjective} str
This property is an adjective that can be used of individuals on the side,
as in @code{"Spanish"}.
Defaults to @code{""}, which suppresses use of the adjective.
@end deffn
As a complete example, a side named @code{"Poland"} would have a long name
@code{"Kingdom of Poland"}, short name @code{"Po"},
noun @code{"Pole"}, plural noun @code{"Poles"},
and adjective @code{"Polish"}.
@deffn SideProperty @code{color} str
This property is a comma-separated list of colors that represents the side.
Defaults to @code{"black"}.
@end deffn
@deffn SideProperty @code{emblem-name} str
This property is the name of a graphical icon that represents the side.
An emblem name of @code{"none"} suppresses any emblem display for the side.
Defaults to @code{""}, which gives the side a randomly-selected emblem.
@end deffn
@deffn SideProperty @code{names-locked} t/f
If the value of this property is @code{true},
then the player cannot modify any of the side's names.
Defaults to @code{false}.
@end deffn
@subsection Side Class
@deffn SideProperty @code{class} str
This property is a side's class, which is a keyword that characterizes the side.
Any number of sides may be in the same class.
Defaults to @code{""}.
@end deffn
@subsection Status in Game
Once a side is in the game, it can never be totally removed.
However, sides can become inactive.
@deffn SideProperty @code{active} t/f
This property is @code{true} if the side is still actively participating in the game.
If the side has won, lost, or simply withdrew, this will be @code{false}.
Any units on a side not in the game are effectively frozen statues;
they don't do anything, and are untouchable by anyone else.
Defaults to @code{true}.
@end deffn
@deffn SideProperty @code{status} lose/draw/win
This property tells how this side did in the game.  Defaults to @code{draw}.
@end deffn
@deffn GlobalConstant @code{win}
@end deffn
@deffn GlobalConstant @code{draw}
@end deffn
@deffn GlobalConstant @code{lose}
These constants are the different possible values for a side's status.
@end deffn
@deffn SideProperty @code{advantage} n
@end deffn
@deffn SideProperty @code{advantage-min} n
@end deffn
@deffn SideProperty @code{advantage-max} n
Initial and min/max limits on advantage for the side.
All default to the values of the corresponding global variables.
@end deffn
@subsection Side Relationships
By default, sides are neutral with respect to each other.
Control is a situation where one side
can observe and move another side's units, but not vice versa.
The controlling side can also just take the units of the controlled side.
If the controlled side loses or resigns, then the controlling side
automatically gets everything.
Both sides must agree to this relationship.
@deffn SideProperty @code{controlled-by} side
This property refers to the side controlling this one.
If 0, then the side is not under control.
Defaults to @code{0}.
@end deffn
The closest side relationship is one of trust.
A trusted side unit's may do anything at any time,
including entering and leaving units on the other side,
consuming the other side's materials, and so forth.
@deffn SideProperty @code{trusts} side-value-list
This property is true for any side that is trusted by this side.
Note that this relationship need not be symmetrical.
Defaults to @code{false} for all sides.
@end deffn
Note that these parameters apply only to relationships as enforced by
@i{Xconq}.  In an actual game, both human and robot sides can make agreements
and have positive/negative opinions about the other sides.
@deffn SideProperty @code{trades} side-value-list
This property defines the trading relationship with other sides.
Defaults to @code{0} for all sides.
@end deffn
@subsection Numbering Units
@deffn SideProperty @code{next-numbers} utype-value-list
This property gives the next serial numbers that will be assigned to units
acquired by this side.
Defaults to @code{1} for each unit type (Dijkstra notwithstanding,
that's still where people start numbering things).
@end deffn
If the unit is of a type that gets numbered
(@code{assign-number} property is true),
then any unit of that type, acquired by any means whatsoever,
will be assigned the @code{next-numbers} value for that type
and @code{next-numbers} will be incremented.
@subsection Side-Specific Namers
A side can have its own set of namers (see below)
that will be used for units
and geographical features associated with that side.
@deffn SideProperty @code{unit-namers} utype-value-list
This property specifies which namers will be used with which types
that the side starts out with or creates new units.
These will not be run automatically on captured units or gifts.
Defaults to @code{""} for each unit type.
@end deffn
@deffn SideProperty @code{feature-namers} feature-type-value-list
This property specifies which namers to use with which geographical
features in the side's initial country (if if has one).
Defaults to @code{()}.
@end deffn
@subsection Tech Levels
The tech level of a side determines what it can do with each type of unit.
@deffn SideProperty @code{tech} utype-value-list
This property assigns a tech level to each unit type named.
Defaults to @code{0} for each unit type.
@end deffn
@deffn SideProperty @code{init-tech} utype-value-list
This property is the tech level at the beginning of the current turn.
Defaults to @code{0} for each unit type.
@end deffn
@subsection Views
These properties are necessary only if the relevant globals
are set a certain way (@code{see-all} is false, etc).
@deffn SideProperty @code{terrain-view} layer-data@dots{}
This property is the side's current knowledge of the world's terrain.
Defaults to @code{()}.
@end deffn
@deffn SideProperty @code{unit-view} layer-data@dots{}
This property is the side's current knowledge of the world.
Defaults to @code{()}.
@end deffn
@deffn SideProperty @code{unit-view-dates} layer-data@dots{}
This property is the turn number at which the unit view data
in the corresponding cell of the @code{unit-view} was set.
Defaults to @code{()}.
@end deffn
@subsection Interaction
@deffn SideProperty @code{turn-time-used} seconds
This property is the number of (real) seconds
that this side has been moving units during the present turn.
Defaults to @code{0}.
@end deffn
@deffn SideProperty @code{total-time-used} seconds
This property is the number of (real) seconds that
this side has been moving units during the course of the game.
Defaults to @code{0}.
@end deffn
@deffn SideProperty @code{timeouts} n
This property is the number of ``time outs'' a side gets for the game.
Defaults to @code{0}.
@end deffn
@deffn SideProperty @code{timeouts-used} n
This property is the number of ``time outs'' a side has already used up.
Defaults to @code{0}.
@end deffn
@deffn SideProperty @code{finished-turn} t/f
This property is true if the side has declared that it is finished moving
things during this turn.
Defaults to @code{false}.
@end deffn
@deffn SideProperty @code{willing-to-draw} t/f
This property is true if the side will go along
with any other side that wants to end the game in a draw.
Defaults to @code{false}.
@end deffn
@deffn SideProperty @code{respect-neutrality} t/f
@end deffn
@deffn SideProperty @code{real-timeout} seconds
This property is the number of (real) seconds to wait before declaring the
side to be finished with this turn.
Defaults to @code{-1}, which waits forever.
@end deffn
@deffn SideProperty @code{task-limit}
This property is the maximum number of tasks a unit is allowed to stack up.
@end deffn
@subsection Doctrine
Doctrines are objects that units consult to decide about individual behavior.
@deffn SideProperty @code{doctrines} utype-property-groups@dots{}
This property is the side's unit-type-specific doctrine.
Each @var{utype-property-group} has the form
@code{(@var{unit-types} doctrine)}.
Defaults to @code{()}.
@end deffn
@deffn SideProperty @code{doctrines-locked} t/f
This property says whether the docrine-unit type correspondence
for the side may be altered during the game.
This property does not control whether or not the properties
of the doctrines may be altered.
Defaults to @code{false}.
@end deffn
@deffn Form @code{doctrine} [id] properties@dots{}
This form creates a doctrine with the given id and properties.
@end deffn
@deffn DoctrineProperty @code{ever-ask-side} t/f
This property is the true if the unit may ask the player for what to do,
instead of picking some default activity.
@end deffn
@deffn DoctrineProperty @code{avoid-bad-terrain} n%
This property is the probability that the unit will not enter
unhealthy terrain, even if it delays meeting goals.
Unhealthy means higher attrition and accident probs, materials
consumed faster than replaced, slower movement.
Defaults to @code{0}.
@end deffn
@deffn DoctrineProperty @code{repair-at} n%
This property indicates that when the unit's hp is at @var{n%} of max,
make a plan to repair.
Defaults to @code{50}.
@end deffn
@deffn DoctrineProperty @code{resupply-at} n%
This property indicates that when the level of a
operationally-consumed material is at @var{n%}
of capacity, try to resupply.
Defaults to @code{50}.
@end deffn
@deffn DoctrineProperty @code{rearm-at} n%
This property indicates that when the level of a
combat-consumed material is at @var{n%}
of capacity, try to resupply.
Defaults to @code{50}.
@end deffn
@deffn DoctrineProperty @code{locked} t/f
This property is true if the properties of the doctrine
cannot be modified by the side's player during the game.
Defaults to @code{false}.
@end deffn
@subsection Other
@deffn SideProperty @code{self-unit} unit
This property is the id of a unit that represents the side itself.
Defaults to @code{0}, which means that no unit represents the side.
See below for more details on self units.
@end deffn
@deffn SideProperty @code{priority} n
The order in which the side will get to act, relative to other sides
and to units.
Defaults to @code{0}.
@end deffn
@deffn SideProperty @code{scores} (skid val)@dots{}
This property is the current values of any numeric scores being
kept for the side.  It is a list of pairs of scorekeeper id and value.
Defaults to @code{()}.
@end deffn
@deffn Form @code{independent-units} properties@dots{}
Like the @code{side} form, but sets properties for independent units.
@end deffn
@deffn SideProperty @code{ui-data} data@dots{}
This property contains interface-specific data for the side.
This is mainly for preservation across game save/restores,
and its form is defined by the interface.
@end deffn
@deffn SideProperty @code{ai-data} data@dots{}
This property is information about the AIs associated with a side.
The format and content of @var{data} is determined by the type(s)
of the AIs.
Defaults to @code{()}.
@end deffn
@section Players
Player objects are rarely necessary when building game designs;
they typically only appear in saved games,
in order to ensure that the same players get the same sides
upon restoration.
@deffn SideProperty @code{player} id
This property is the unique identifier of a player that is running this side.
Defaults to @code{0}, which means that no player has been assigned
to the side.
@end deffn
@deffn Form @code{player} [id] properties@dots{}
This form defines a player.
If the @var{id} is supplied and matches the id of an existing player,
then the player object is updated using the @var{properties},
otherwise a new player object will be created,
using the given @var{id} if supplied, otherwise creating a new value.
@end deffn
@deffn GlobalVariable @code{player-sides-locked} t/f
This variable is @code{true} if the player/side assignment may not
be changed while the game is starting up.
Defaults to @code{false}.
@end deffn
The number of players must always be less than the number of sides
(sides without players just don't do anything).
@deffn PlayerProperty @code{name} str
This property identifies the player by name.
Defaults to @code{""}.
@end deffn
@deffn PlayerProperty @code{config-name} str
This property identifies a particular set of doctrine and other definitions
that the player is using.
Defaults to @code{""}.
@end deffn
@deffn PlayerProperty @code{display-name} str
This property identifies the display being used by the player's interface.
The interpretation of this value is dependent on the interface in use.
Defaults to @code{""}.
@end deffn
@deffn PlayerProperty @code{ai-type-name} str
This property is the type of AI that will play the side
if requested or necessary.
The set of choices depends on what has been compiled into @i{Xconq}.
(The general-purpose AI type @code{"mplayer"} will usually be available,
but is not guaranteed.)
An @code{ai-type-name} of @code{""} means that no AI will run this player.
Defaults to @code{""}.
@end deffn
@deffn PlayerProperty @code{password} str
This property is the encoding of a password that must be entered before this
player object can be reused successfully.
Defaults to @code{""}.
@end deffn
@deffn PlayerProperty @code{initial-advantage} n
This property is an initial relative strength at which the player should start.
Some synthesis methods can use this to give more units or some other
advantage to each player according to the requested strength.
Defaults to @code{1}.
@end deffn
@deffn GlobalVariable @code{advantage-min} n
@end deffn
@deffn GlobalVariable @code{advantage-max} n
@end deffn
@deffn GlobalVariable @code{advantage-default} n
These variables set the bounds and default values for players'
initial advantages.
Default to @code{1}, @code{9999}, and @code{1}, respectively.
@end deffn
@i{Xconq} is not guaranteed to be able to be able to set up a game
with any combination of player advantages;
the limits depend on the capabilities and characteristics of the
synthesis methods that use the requested advantages in their
calculations.
@subsection Rules of Side Configuration
The properties of a side can come from a number of different sources
(here listed in order of precedence):
@itemize
@item
Interface-specific sources (X resources, Mac preferences).
@item
Game-specific form in player's configuration file.
@item
Generic form in player's configuration file.
@item
The @code{side} form for the side.
@item
The @code{side-defaults} form for the game.
@item
General program defaults.
@end itemize
Note that interface-specific and general config files can never alter
certain properties of a side, and can only alter others if they are
not locked.
@section Units
The basic @code{unit} form creates or modifies a unit.
@deffn Form @code{unit} id [ type ] properties@dots{}
This form defines a unit.
If a numeric @var{id} is supplied and matches the id of an existing unit,
then that unit will be modified by @var{properties},
and the optional @var{type} will be interpreted as a new type for the unit.
Otherwise a new unit will be created,
with either @var{id} as its id or
a arbitrarily-selected one if @var{id} is already in use.
If the unit's id is newly-generated and no type has been specified,
then type #0 (first-defined type) will be the type of the unit.
An id of @code{0} can never match an existing unit id, so effect
will be as if it had been omitted.
@end deffn
@deffn Form @var{unit-type-name} x y [ side-id ] properties@dots{}
This is an abbreviated form, in which
the x,y position is required, and an optional side id may be included.
The side id will come from @code{unit-defaults} if not specified.
The @var{unit-type-name} may be any valid unit type name or
defined name.
This form always results in a new unit.
@end deffn
Since there may be many units whose properties are similar, there
is a ``default unit'' whose properties fill in missing properties in
individual unit declarations.
@deffn Form @code{unit-defaults} [ modifier ] properties@dots{}
This form sets the default values for all subsequent units read in,
in this and every other module not yet loaded.
The set of defaults is additive,
so for instance you can repeatedly change the default side of units.
If the symbol @code{reset} has been supplied for the optional @var{modifier},
then all the defaults will be changed to the basic default
values, as described in this manual.
@end deffn
@deffn Symbol @code{reset}
This is the symbol used to reset unit defaults; see above.
@end deffn
@subsection Unit Properties
This section lists properties of individual units.
In general, they default to the most common or reasonable values,
so need not always be specified, even in a saved game.
@deffn UnitProperty @code{@@} x y [ z ]
This property is the position of the unit.
Defaults to @code{-1,-1,0}, which causes the unit to be placed randomly.
The optional altitude @var{z} can also be set separately with
the property @code{z} below.
If @i{z} is even and the unit is in the open,
then the unit's altitude is @i{z/2};
if @i{z} is odd, then @i{(z-1)/2} is the type of connection terrain
that the unit is on.
@end deffn
@deffn UnitProperty @code{z} z
This property is identical to the optional z part of the @code{@@} property.
Defaults to @code{0}.
@end deffn
@deffn UnitProperty @code{s} side
This property is the side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of @code{0} or @code{"independent"}
means that the unit is independent.
Defaults to @code{0}.
@end deffn
@deffn UnitProperty @code{#} n
This property is the unique numeric id of the unit.
Defaults to a game-selected value.
@end deffn
@deffn UnitProperty @code{n} str
This property is the name of the unit.
Defaults to @code{""}.
@end deffn
@deffn UnitProperty @code{nb} n
This property is the number of the unit,
which starts at @code{1} and goes up.
Defaults to @code{0}, which means that the unit is unnumbered.
@end deffn
@deffn UnitProperty @code{cp} n
This property is the current completeness of the unit.
If negative, indicates that the unit will appear at a time
and place specified by the @code{appear} x-property.
Defaults to the @code{cp-max} for the type.
@end deffn
@deffn UnitProperty @code{hp} n
This property is the current hit points of the unit.
Will be restricted to the range [0, hp-max].
An hp of 0 means that the unit is dead and will not appear in the game.
Defaults to @code{hp-max} for the unit's type.
@end deffn
@deffn UnitProperty @code{cxp} cxp
This property is the combat experience of the unit.
Defaults to @code{0}.
@end deffn
@deffn UnitProperty @code{mo} n
This property is the morale of the unit.
Defaults to @code{0}.
@end deffn
@deffn UnitProperty @code{m} mtype-value-list
This property is the amounts of supplies being carried by the unit.
Defaults to @code{0} for each material type.
@end deffn
@deffn UnitProperty @code{tp} utype-value-list
This property is the level of tooling to build each type of unit.
Defaults to @code{0} for each unit type.
@end deffn
@deffn UnitProperty @code{in} n
This property is the id of the unit's transport.
Defaults to @code{0}, meaning that unit is not in any transport.
@end deffn
@deffn UnitProperty @code{opinions} side-value-list@dots{}
This property is the unit's true feelings towards each side,
including its own side.
Defaults to @code{0} for each side.
@end deffn
@deffn UnitProperty @code{x} obj
This property is the optional extension properties of the unit.
Its value may be any object.
Defaults to @code{()}.
@end deffn
@deffn Symbol @code{appear}
@end deffn
@deffn Symbol @code{disappear}
These are extension properties that indicate
when and where a unit will appear in the game,
and when it will disappear.
[syntax?]
@end deffn
@subsection Unit Action State
@deffn UnitProperty @code{act} subprops
This property specifies the current action state of the unit.
@end deffn
@deffn UnitActionStateProperty @code{acp} n
This property is the number of action points left to the unit for this turn.
Defaults to @code{0}.
@end deffn
@deffn UnitActionStateProperty @code{acp0} n
This property is the initial number of action points for this turn,
computed at the beginning of the turn.
Defaults to @code{0}.
@end deffn
@deffn UnitActionStateProperty @code{aa} n
This property is the actual number of actions executed by the
unit so far in the current turn.
Defaults to @code{0}.
@end deffn
@deffn UnitActionStateProperty @code{am} n
This property is the actual number of moves (cell entries)
executed so far in the current turn.
Defaults to @code{0}.
@end deffn
@deffn UnitActionStateProperty @code{a} action
This property is the next action that the unit will perform.
@end deffn
Note that if any unit-defining form has an @code{act} property,
@i{Xconq} will start at an appropriate point in the middle of a turn,
giving all other units zero acp and mp,
rather than starting at the beginning of the turn
and computing acp and mp for all units.
@subsection Unit Plan
@deffn UnitProperty @code{plan} type [subtype] properties@dots{}
This property describes the unit's current plan.
@end deffn
@deffn PlanType @code{none}
A unit with this type of plan does nothing.
It is used when a side has no player.
@end deffn
@deffn PlanType @code{passive}
This plan type is for units on a side that is being run directly
by the side.
@end deffn
@deffn PlanType @code{defensive}
This plan type is for units that defend areas or other units.
@end deffn
@deffn PlanType @code{exploratory}
This plan type is for units that explore the world.
@end deffn
@deffn PlanType @code{offensive}
@end deffn
@deffn PlanType @code{random}
A unit with this plan type will act randomly.
@end deffn
@deffn PlanProperty @code{goal}
This property is the main goal of a unit's plan.
@end deffn
The possible types of goals are these:
@deffn GoalType @code{no-goal}
@end deffn
@deffn GoalType @code{won-game}
@end deffn
@deffn GoalType @code{lost-game}
@end deffn
@deffn GoalType @code{world-is-known}
@end deffn
@deffn GoalType @code{vicinity-is-known}
@end deffn
@deffn GoalType @code{positions-known}
@end deffn
@deffn GoalType @code{cell-is-occupied}
@end deffn
@deffn GoalType @code{vicinity-is-held}
@end deffn
@deffn GoalType @code{has-unit-type}
@end deffn
@deffn GoalType @code{has-unit-type-near}
@end deffn
@deffn GoalType @code{has-material-type}
@end deffn
@deffn GoalType @code{keep-formation}
@end deffn
[also support some kind of hook for specific AIs?]
@deffn PlanProperty @code{tasks} tasks@dots{}
This property is the complete task agenda for the unit's plan.
It is a list of tasks.
Defaults to @code{()}.
@end deffn
@deffn TaskType @code{build} u n n2 unit-id
@end deffn
@deffn TaskType @code{capture} unit-id
@end deffn
@deffn TaskType @code{do-action} action
@end deffn
@deffn TaskType @code{hit-position} x y z
@end deffn
@deffn TaskType @code{hit-unit} unit-id
@end deffn
@deffn TaskType @code{move-dir} dir
@end deffn
@deffn TaskType @code{move-to} x y z dist
@end deffn
@deffn TaskType @code{occupy} unit
@end deffn
@deffn TaskType @code{pickup} unit
@end deffn
@deffn TaskType @code{repair} unit
@end deffn
@deffn TaskType @code{resupply}
@end deffn
@deffn TaskType @code{sentry} n
@end deffn
@deffn PlanProperty @code{asleep} t/f
This property is true if the unit is asleep.
Defaults to @code{false}.
@end deffn
@deffn PlanProperty @code{reserve} t/f
This property is true if the unit is in reserve.
Defaults to @code{false}.
@end deffn
@deffn PlanProperty @code{wait} t.f
This property is true if the unit is waiting for orders.
Defaults to @code{false}.
@end deffn
@deffn PlanProperty @code{formation} goal
@end deffn
@section Agreements
@deffn Form @code{agreement} [name/id] properties@dots{}
This form defines an agreement among a set of sides.
The name/id is a unique internal identifier.
@end deffn
@deffn AgreementProperty @code{type-name} str
This property is the name of the general type of agreement,
such a trade.
Defaults to @code{""}.
@end deffn
@deffn AgreementProperty @code{title} str
This property is the player-visible name of the agreement.
Defaults to @code{""}.
@end deffn
@deffn AgreementProperty @code{terms} forms@dots{}
This property is the list of terms of the agreement.
Defaults to @code{()}.
@end deffn
@deffn AgreementProperty @code{drafters} side-list
This property is the side that initially proposed the agreement.
@end deffn
@deffn AgreementProperty @code{proposers} side-list
This property is the side that initially proposed the agreement.
@end deffn
@deffn AgreementProperty @code{signers} side-list
Before the agreement is made,
this property is the proposed list of participants.
After the agreeement is made,
this is the actual list of participants.
@end deffn
@deffn AgreementProperty @code{willing-to-sign} side-list
This property is all the sides that have already agreed to this agreement,
on condition that all the other sides accept it.
@end deffn
@deffn AgreementProperty @code{known-to} side-list
@end deffn
@deffn AgreementProperty @code{enforcement} form
@end deffn
[include values such as @code{enforced} and @code{publicity}?]
@deffn AgreementProperty @code{state} state
@end deffn
[add symbols for states]
@node Scorekeepers, History Design, Unit Design, Game Design
@section Scorekeepers
Scorekeepers are the objects that manage scoring, winning, and losing.
A game design need not define any scorekeepers,
and none are created by default.
A scorekeeper may either maintain a numeric score that is used at
the end of the game to decide rankings, or simply declare a side
to have won or lost.
@deffn Form @code{scorekeeper} name properties@dots{}
This form creates or modifies a scorekeeper with the given @var{name},
with the given @var{properties}.
@end deffn
@deffn ScorekeeperProperty @code{title} str
This property is a string that identifies the scorekeeper to the players.
Defaults to @code{""}.
@end deffn
@deffn ScorekeeperProperty @code{when} (type [exp])
This property is when the scorekeeper will be checked or updated.
Defaults to @code{after-turn}.
@end deffn
@deffn ScorekeeperWhenType @code{before-turn} exp
This indicates that the scorekeeper will run at the start of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn
@deffn ScorekeeperWhenType @code{after-turn} exp
This indicates that the scorekeeper will run at the end of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn
@deffn ScorekeeperWhenType @code{after-event} exp
This indicates that the scorekeeper will run after every event
matching @var{exp}, or after every event if @var{exp} is not given.
@end deffn
@deffn ScorekeeperWhenType @code{after-action} exp
This indicates that the scorekeeper will run at the end of each action
matching @var{exp}, or after every action if @var{exp} is not given.
@end deffn
@deffn ScorekeeperProperty @code{applies-to} side-list
This property is the set of sides or side classes
to which the scorekeeper applies.
Scorekeepers apply only to sides that are in the game.
Defaults to @code{side*}.
@end deffn
@deffn ScorekeeperProperty @code{known-to} side-list
This property is the list of sides that know about this scorekeeper,
and can see the value of the score for each side that it applies to.
Defaults to @code{side*}.
@end deffn
@deffn ScorekeeperProperty @code{trigger} form
This property is an expression that is true when it is time
to start checking the scorekeeper's main test.
Once a scorekeeper is triggered, it remains active.
Defaults to @code{false}.
@end deffn
@deffn ScorekeeperProperty @code{triggered} t/f
This property is true if the scorekeeper is currently triggered.
Defaults to @code{true}.
@end deffn
@deffn ScorekeeperProperty @code{do} forms@dots{}
This property is a list of forms to execute in order
each time the scorekeeper runs.
Defaults to @code{()}.
@end deffn
@deffn ScorekeeperProperty @code{messages} forms@dots{}
This property is a list of messages to be sent [???].
Defaults to @code{()}.
@end deffn
@deffn ScorekeeperProperty @code{initial} value
This property is the value of the score upon game startup.
If this value is @code{-9999},
the scorekeeper does not maintain a numeric score.
Defaults to @code{-9999}.
@end deffn
@subsection Bodies
The forms in the body (the @code{do} property) of the scorekeeper
may be any of the forms listed here.
@deffn ScorekeeperForm @code{last-side-wins}
If supplied as the only symbol in the body, then the scorekeeper
implements the usual ``last side left in the game wins'' behavior.
@end deffn
@deffn ScorekeeperForm @code{if} test action
If the @i{test} evaluates to @code{true} or any nonzero number,
then the @i{action} will be done.
@end deffn
@deffn ScorekeeperForm @code{cond} (test actions@dots{}) @dots{}
This is like Lisp's cond.
@end deffn
@deffn ScorekeeperForm @code{stop} [message]
This stops the game immediately, with a draw for all sides.
@end deffn
@deffn ScorekeeperForm @code{win} [sides] [own-message] [other-message]
@end deffn
@deffn ScorekeeperForm @code{lose} [sides] [own-message] [other-message]
@end deffn
@deffn ScorekeeperForm @code{end} [message]
This scorekeeper action ends the game immediately.
@end deffn
@deffn ScorekeeperForm @code{add} exp [side]
This adds the result of evaluating @var{exp} to the score of the given side.
The value may be a negative number.
@end deffn
@subsection Scorekeeper Functions
@deffn ScorekeeperFunction @code{and} exps
@end deffn
@deffn ScorekeeperFunction @code{or} exps
@end deffn
@deffn ScorekeeperFunction @code{not} exp
@end deffn
@deffn ScorekeeperFunction @code{=} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{/=} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{>} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{>=} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{<} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{<=} exp1 exp2
@end deffn
@deffn ScorekeeperFunction @code{sum} types properties [test]
@end deffn
@subsection Scorefile
@deffn GlobalVariable @code{scorefile-name} str
@end deffn
@c [scorefile must include xconq version, module(s) plus versions,
@c player/side setup, dates/times, and list of scores/values plus
@c optional id as to which is which]
@node History Design, Battle States, Scorekeeper Design, Game Design
@section The History
All the important events in a game are logged into a history.
@deffn Form @code{evt} [ date ] type [ sides ] data
This form creates a single historical event.
If @i{date} is omitted, then the date will be the
same turn as for the last event read.
@end deffn
@deffn Form @code{exu}
@end deffn
@deffn EventType @code{log-started}
This event records when the recording of events began.
Multiple instances of this may occur, for instance if
logging were to be turned off and then on again.
@end deffn
@deffn EventType @code{log-ended}
@end deffn
@deffn EventType @code{game-started}
This event records the actual start of the game.
There should only be one in a game's history.
@end deffn
@deffn EventType @code{game-saved}
@end deffn
@deffn EventType @code{game-restarted}
@end deffn
@deffn EventType @code{game-ended}
@end deffn
@deffn EventType @code{side-joined}
This event records when a side joined the game.
@end deffn
@deffn EventType @code{side-lost}
This event records when a side lost.
@end deffn
@deffn EventType @code{side-withdrew}
This event records when a side withdrew from the game.
@end deffn
@deffn EventType @code{side-won}
This event records when a side won.
@end deffn
@deffn EventType @code{unit-started-with}
[???]
@end deffn
@deffn EventType @code{unit-created} id
This event records the creation of a unit.
@end deffn
@deffn EventType @code{unit-completed}
This event records the completion of a unit.
@end deffn
@deffn EventType @code{unit-acquired}
This event records the acquisition of a unit,
for instance as a gift from another side.
@end deffn
@deffn EventType @code{unit-captured}
This event records the capture of a unit,
as an outcome of combat or from a direct attempt to capture.
@end deffn
@deffn EventType @code{unit-moved} id x1 y1 x2 y2
This event records the movement of a unit.
@end deffn
@deffn EventType @code{unit-name-changed}
@end deffn
@deffn EventType @code{unit-type-changed}
@end deffn
@deffn EventType @code{unit-assaulted}
@end deffn
@deffn EventType @code{unit-damaged}
@end deffn
@deffn EventType @code{unit-killed}
@end deffn
@deffn EventType @code{unit-vanished}
@end deffn
@deffn EventType @code{unit-wrecked}
@end deffn
@deffn EventType @code{unit-garrisoned}
@end deffn
@deffn EventType @code{unit-disbanded}
@end deffn
@deffn EventType @code{unit-starved}
@end deffn
@deffn EventType @code{unit-left-world}
@end deffn
The following event types are the results of actions.
@deffn EventType @code{action-ok}
@end deffn
@deffn EventType @code{action-error}
@end deffn
@deffn EventType @code{cannot-do}
@end deffn
@deffn EventType @code{insufficient-acp}
@end deffn
@deffn EventType @code{insufficient-material}
@end deffn
@deffn EventType @code{action-done}
@end deffn
@c should flush this one
@deffn EventType @code{insufficient-mp}
@end deffn
@deffn EventType @code{cannot-leave-world}
@end deffn
@deffn EventType @code{destination-too-far}
@end deffn
@deffn EventType @code{destination-full}
@end deffn
@deffn EventType @code{overrun-failed}
@end deffn
@deffn EventType @code{overrun-failed}
@end deffn
@deffn EventType @code{fire-into-outside-world}
@end deffn
@deffn EventType @code{fire-into-too-far}
@end deffn
@deffn EventType @code{fire-at-too-far}
@end deffn
@deffn EventType @code{fire-into-too-near}
@end deffn
@deffn EventType @code{fire-at-too-near}
@end deffn
@deffn EventType @code{too-far}
@end deffn
@deffn EventType @code{too-near}
@end deffn
@node Battle States, , History Design, Game Design
@section Battle States
Battles always have exactly two ``sides'', referred to as
the attacker-list or A-list and the defender-list or D-list, so
as not to confuse them with sides in the game.
@deffn Form @code{battle} a-list d-list@dots{}
@end deffn
Each list has the form
@example
((<unit> <commitment>) ...)
@end example
@section Types in General
Types are the foundation of @i{Xconq} game designs.
Nearly all the rules and game parameters are associated
with the unit, material, and terrain types.
There is no sort of type hierarchy; instead, most forms allow sets of types
to be used in the place of single types.
Each type has an index associated with it, starting from 0.
This index never appears directly, and cannot be set.
This does mean that types have an order, so the order in which
types are defined is sometimes significant.
These cases will be noted.
The order is always the order in which the types appear in the file,
so it is always the same.
@subsection Naming
The names of types need not be distinct from each other,
but you run the risk of player confusion if they share names.
@deffn TypeProperty @code{name} string
This property is the specific name of the type.
This name will be displayed to players; the exact format
is up to the interface, but will typically
depend on the name's length and the space available in the display.
If no type names have been defined, the internal type name (see below)
will be used.
Defaults to @code{""}.
@end deffn
@deffn TypeProperty @code{long-name} string
This property is a fully spelled-out name for the type.
Defaults to @code{""}.
@end deffn
@deffn TypeProperty @code{short-name} string
This property is an abbreviated name of r
Defaults to @code{""}.
@end deffn
@deffn TypeProperty @code{generic-name} string
This property is like @code{name}, but identifies the type less specifically,
and several types may have the same generic name.
If no generic names are defined, then the regular type names will be used.
This is useful when making abbreviated lists, so that related types
get counted together.
Defaults to @code{()}.
@end deffn
As an example of the distinction between type names and generic type name,
the names of a automobile type might be @code{"1965 Mustang"},
@code{"Mustang"}, and @code{"M"},
while the generic name is @code{"auto"}.
Then the interface could choose to display a parking lot as containing
either @code{"4 auto"} or @code{"2 Mustang 1 Edsel 1 Jeep"}.
Note that names specified as properties are strings only, and are
not defined as evaluable symbols.
@subsection Imaging
The interpretation of these properties is entirely up to each interface;
see the appropriate interface documentation for details.
@deffn TypeProperty @code{image-name} str
This property is the name of the type's image.
If undefined or unusable for some reason,
the interface will display the type in some default manner, such as
a solid-color square or a string.
@end deffn
For example, in X11,
the name might be the name of a file in the usual bitmap format, as
produced by the @var{bitmap} program.  The actual file name is produced
by appending @code{".b"}.
(The situation in X is actually more complicated than this.)
See the interface documentation for details on how the interface
uses the image.
@deffn TypeProperty @code{color} str
This property is the name of the preferred color for this type.
Both normal color names and the strings @code{"bg"} and @code{"fg"}
(meaning ``foreground color'' and ``background color'')
may be used.
If the image is in color, then this property has no effect.
Defaults to @code{"fg"}.
@end deffn
@deffn TypeProperty @code{char} str
This property supplies a single character for this type
(all characters after the first one in @var{str} are ignored).
Defaults to @code{""}.
@end deffn
@subsection Documentation
@deffn TypeProperty @code{description-format} list@dots{}
This property defines the different ways in which
an instance or instances of this type may be described textually.
This information may be used in narrative descriptions and by some
interfaces.
[describe syntax of the lists - are similar to name grammars]
If @code{()}, then the instance will be described in some default
fashion, such as (for units) @code{"the <side> <ordinal> <type>"}.
Defaults to @code{()}.
@end deffn
@deffn TypeProperty @code{help} string
This property is a brief (preferably one-line) description of the type.
Defaults to @code{""}.
@end deffn
@deffn TypeProperty @code{notes} strings@dots{}
This property is detailed documentation about the type.
The formatting of the strings is up to the interface,
but in general each string is a separate line,
the string @code{""} indicates a line break,
and two @code{""} in a row indicates a paragraph break.
Defaults to @code{()}.
@end deffn
@subsection Availability
It may be that a set of types is larger than strictly necessary for
a particular game.  You can make any type unavailable, which means
that irrespective of any other controls, that type cannot come into
play during a game.  You can also make it available only for particular
turns.
@deffn TypeProperty @code{available} n
If the value of this property is greater than 0, then this type is available
in the game on or after turn @var{n}.
If the value is less than 0, then the type is available,
but only until turn @var{-n}.
If the value is 0, then the type is never available.
Defaults to @code{1}, which means that the type is always available.
@end deffn
If a type becomes unavailable and there are units of that type in play,
then they will vanish immediately.
@subsection Type Extension
It may occasionally be necessary to add new kinds of
information to a type.
For instance, new synthesis methods may require special data,
or an interface may be able to use extra hints to improve its display.
The @code{extensions} property can be used to store this kind of data.
@deffn TypeProperty @code{extensions} properties@dots{}
This property is a catch-all for nonstandard type properties.
Anything may appear here, but it will only be interpreted as much as needed,
and unrecognized extensions will not be warned about (so if you misspell
one, you won't find out).
@end deffn
@node Unit Types, Command Chain, General, Type Definition
@section Unit Types
@deffn Form @code{unit-type} symbol properties@dots{}
This form defines a new type of unit.
The @var{symbol} is required and must be previously undefined.
The bindings in @var{properties} are then added to the type one by one.
If no other name properties are defined, the @var{symbol} may be displayed
to players (see above).
You can define no more than 126 types of units.
@end deffn
The @var{symbol} here becomes the unit type's ``internal type name''
which is guaranteed unique.
To make synonyms for the internal type name, use @code{define}.
@deffn GlobalVariable @code{u*}
This variable evaluates to a list of all unit types,
listed in the order that they were defined.
This list always reflects the list of types at the moment it is evaluated.
@end deffn
@deffn GlobalVariable @code{non-unit}
This variable [constant?] evaluates to a value that is NOT a unit type.
This is needed in several places to enable/disable features.
Use of this in any other way is an error,
and may or may not be detected before it causes a crash.
@end deffn
@subsection Unit Naming
@deffn UnitTypeProperty @code{namer} namer-id
This property is the namer that will be used to generate names for units,
if the unit's side does not have a namer, or the unit is
independent and not in any country.
Defaults to @code{0}, which leaves the unit unnamed.
@end deffn
@deffn UnitTypeProperty @code{assign-number} t/f
This property is true if the unit should have a serial number assigned to it
by the side it belongs to.
Serial numbers are maintained for each type on each side separately,
start at 1 for the first unit of the type, and increase by one each time.
Defaults to @code{true}.
@end deffn
@subsection Class-Restricted Unit Types
Sometimes the designer will want to make different sides have different types
of units.  Although this can be done by setting up scenarios appropriately,
that won't close all the loopholes that might allow a side to get units that
should only ever belong to another side.
The first step is to define a class for each side.  For instance,
a side named @code{"Rome"} might have a class @code{"Roman"},
while the sides named @code{"Aedui"} and @code{"Parisii"}
could both be in the class @code{"barbarian"}.
@deffn UnitTypeProperty @code{possible-sides} exp
This property restricts the unit type to only be usable
by a side meeting the conditions of @var{exp}.
If @var{exp} is a string, it restricts the unit type to only
be usable by a side whose class includes a matching string.
This can also be a boolean combination.
Independent units belong to a side whose class is @code{"independent"}.
The default of @code{""} allows the unit to belong to any side.
@end deffn
@subsection Self-Units
The self-unit can be any type, including one that cannot act;
for instance, a capital city could be the self-unit, thus making
its defense all-important for a player.
@deffn GlobalVariable @code{self-required} t/f
This variable is true if each side is required to have a self-unit
at all times.
However, if no unit of a suitable type is available when the game begins,
then none will be required.
Defaults to @code{false}.
[this should also have a related side property?]
[rounding-down advantage should not eliminate one needed as self-unit?]
@end deffn
@deffn UnitTypeProperty @code{can-be-self} t/f
This property says that the type of unit can represent the side directly.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{self-changeable} t/f
This property is true if the player can choose to change a self-unit of
this type at any time.
Otherwise the self-unit can be changed only if the current one dies.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{self-resurrects} t/f
This property is true if when the self-unit dies, another unit of an allowable type
becomes the self-unit automatically.
Defaults to @code{false}.
@end deffn
Observe that these parameters can be used to develop various forms of
backup, so that a player can start out as a capital city, resurrect as
a town, change self to one of several towns, then lose when all the towns
are lost.
@deffn UnitTypeProperty @code{direct-control} t/f
This property is true if a unit of this type can be controlled by its side
automatically.
If false, then it must be within range of a unit that can control it,
and is itself under control by the side.
Defaults to @code{true}.
@end deffn
@deffn Table @code{control-chance-at} u1 u2 -> n%
@end deffn
@deffn Table @code{control-chance-adjacent} u1 u2 -> n%
@end deffn
@deffn Table @code{control-chance} u1 u2 -> n%
@end deffn
@deffn Table @code{control-range} u1 u2 -> dist
This table gives the maximum distance from self-unit @var{u1}
at which units of type @var{u2}
can be controlled directly.  Units further away always act on their own
(as if the doctrine said so[?]).
If this value is < 0, then @var{u1} can never directly control
any other @var{u2} on the side.
Defaults to @code{infinity}.
@end deffn
@subsection Limiting Unit Quantities
The effect of these is
to prevent any extra units from being created or from going over to a
side, regardless of the reason.
This happens by either preventing player actions that would
result in exceeding a limit (such as when building units), or by making
the unit vanish instantly (such as when capturing a unit).
@deffn GlobalVariable @code{units-in-game-max} n
This variable is the maximum number of all types of units, on all sides,
including independents, that may exist at any time, including initially.
Defaults to @code{-1}, which means that there is no limit.
@end deffn
@deffn GlobalVariable @code{units-per-side-max} n
This variable is the maximum number of units (of all types together)
that any side may have, at any time.  Events that would cause
the limit to be exceeded, such as capturing a unit, result in
either the unit vanishing or becoming independent.
Defaults to @code{-1}, which means that there is no limit.
@end deffn
There is no limit on the number of units that may be independent.
@deffn UnitTypeProperty @code{type-in-game-max} n
This property is the maximum total of the given type, for all sides together.
Defaults to @code{-1}, which means that there is no limit.
@end deffn
@deffn UnitTypeProperty @code{type-per-side-max} n
This property is the maximum number of units of the given type allowed to each side.
Defaults to @code{-1}, which means that there is no limit.
@end deffn
@subsection Hit Points
A unit's hit points determine how healthy it is.
If a unit's hp goes below 1, it is either @dfn{wrecked},
meaning that it changes to a new type
@code{wrecked-type} or else it @dfn{vanishes},
meaning that it is completely cleared from the world.
@deffn UnitTypeProperty @code{hp-max} n
This property is the maximum number of hit points for (each part of) a unit.
Completed units start with this many hit points.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{parts-max} n
This property declares that a unit is to be treated
as an aggregate of @var{n} smaller identical units.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{wrecked-type} unit-type
This property is the type of unit that a unit with 0 hp will become.
For instance, a destroyed ``fort'' might become a ``rubble pile'' unit.
If its value is @code{non-unit}, then the destroyed unit just vanishes.
The @code{wrecked-type} of a type must be a different type.
Defaults to @code{non-unit}.
@end deffn
The transformation to the wrecked type does not change position or name.
The transformed unit has full hp, supplies are conserved as much as possible,
tooling is preserved, and any unit plan is erased.
It has the same number of parts, or as many as possible if that is fewer.
It may be that the
wrecked type is on terrain that it cannot survive on; in that case, it
will be wrecked again, repeating until the unit either vanishes
or is in a viable position, or this process has been repeated
more times than the number of unit types (prevents infinite loops).
Any excess occupants will be removed and either placed in another nearby
unit or in the open, or will vanish if there is no other option.
@deffn UnitTypeProperty @code{hp-recovery} n
This property is the number of 1/100 hp recovered per turn.
Recovery happens automatically, as opposed to repair,
which requires explicit action.
The amount @i{n} / 100 is recovered automatically each turn,
while @i{n} mod 100 is the percent chance of recovering 1 hit point
in addition.
Defaults to @code{0}.
@end deffn
@subsection Experience
@deffn UnitTypeProperty @code{cxp-max} cxp
This property is the maximum combat experience this type of unit can have.
Defaults to @code{0}.
@end deffn
@subsection Tech Levels
Before it can do anything with a type of unit,
the side must have the appropriate tech level for that type,
which is just a number ranging from 0 up to @code{tech-level-max}.
Each type has a distinct tech level.
Tech levels always increase
(since they represent abstract knowledge rather than physical plant).
Tech can be transferred freely to any other side
via the message @code{tech} [xref to messages].
For each unit type, the following parameters define the minimum tech levels at
which sides can do various things.
@deffn UnitTypeProperty @code{tech-to-see} tl
This property is the minimum tech level that a side must have before it can see
a unit of this type.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-to-own} tl
This property is the minimum tech level
that a side must have in order to have a unit of this type.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-from-ownership} tl
This property is the tech level that may be reached
by acquiring a unit of this type.
Since this is expressed as a minimum,
multiple acquisitions have no additional effect.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-to-use} tl
This property is the minimum tech level that a side must have in order to
give actions to this type of unit.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-to-build} tl
This property is the minimum tech level that a side
must have in order to build this type of unit.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-max} tl
This property is the absolute maximum tech level possible for this type.
Defaults to @code{0}.
@end deffn
@deffn Table @code{tech-crossover} u1 u2 -> n%
This table is the minimum tech level for @var{u2} that is guaranteed by a particular
tech level for @var{u1}, expressed as a percentage of the @code{tech-max}
for the types.
For instance, if @code{tech-crossover} is 80, and the tech level for @var{u1}
is 10 out of a max of 20, and the max for @var{u2} is also 20,
then the side has a tech for @var{u2} at least 8.
Defaults to @code{0}.
@end deffn
It is possible to gain some tech level just by being in the same game
with a side that is more advanced.
@deffn UnitTypeProperty @code{tech-leakage} .01tl
This property is the amount of tech level gain per turn that can happen
to any side's tech level that is less than the max of all sides in the game.
This only happens if at least one unit on the side has nonzero coverage
of a unit on a more advanced side.
Defaults to @code{0}.
@end deffn
@subsection Opinions
@deffn UnitTypeProperty @code{has-opinions} t/f
This property is true if the unit has opinions about sides,
both other sides and its own.
Defaults to @code{false}.
@end deffn
@subsection Point Value
Point values provide an abstract way to characterize the overall importance
of a unit type.
Point values figure into some scorekeepers, and are used by AIs.
@deffn UnitTypeProperty @code{point-value} n
This property is the ``value'' of a unit.
Defaults to @code{1}.
@end deffn
@node Terrain Types, Material Types, Point Value, Type Definition
@section Terrain Types
Terrain types are associated with the cells, borders,
connections, and coatings in a world.
@deffn Form @code{terrain-type} name properties@dots{}
This form defines a new type of terrain, named by @var{name}.
Details are similar to those for unit types.
@end deffn
@deffn GlobalVariable @code{t*}
This variable evaluates to a list of all terrain types,
listed in the order that they were defined.
@end deffn
@deffn GlobalVariable @code{non-terrain}
This variable has a value that is guaranteed not to be a terrain type.
@end deffn
@subsection Terrain Subtypes
Terrain can appear in four different roles: as the interior of
a cell, as a border between cells, as a connection between cells,
or as a coating overlaying the normal terrain.
The terrain subtype says which role a type can play.
@deffn TerrainTypeProperty @code{subtype} subtype
This property is the role that the terrain type can appear in.
Defaults to @code{cell}.
@end deffn
@deffn GlobalConstant @code{cell}
This constant indicates that terrain can fill a cell.
All units in the open and with an altitude of 0 are assumed
to be surrounded by the cell terrain.
@end deffn
@deffn GlobalConstant @code{border}
This constant indicates that the terrain can be a border.
@end deffn
@deffn GlobalConstant @code{connection}
This constant indicates that the terrain can be a connection.
@end deffn
@deffn GlobalConstant @code{coating}
This constant indicates that the terrain can be a coating.
A @dfn{coating} is a temporary terrain modification.
The classic example is snow,
which effectively changes some kinds of terrain,
but not completely and usually not permanently.
Cells can have varying heaviness of each type of coating.
@end deffn
@deffn Table @code{coating-depth-min} t1 t2 -> n
In order for a coating @var{t1} to ``stick'',
this table says much must be added all at once to terrain @var{t2}.
A coating depth that drops below this will disappear immediately.
Defaults to @code{0}.
@end deffn
@deffn Table @code{coating-depth-max} t1 t2 -> n
This table is the upper limit on coating depth.
Defaults to @code{0}.
@end deffn
Terrain types may have additional subtype attributes that
are used only during synthesis, to select appropriate subtypes
for special purposes.
@deffn TerrainTypeProperty @code{subtype-x} n
This property is extra subtype information, used in synthesis.
Defaults to @code{no-x}.
@end deffn
@deffn GlobalConstant @code{no-x}
@end deffn
@deffn GlobalConstant @code{river-x}
This constant indicates that synthesis methods should treat this
type as a river.
The terrain type may be either a border or a connection.
@end deffn
@deffn GlobalConstant @code{valley-x}
This constant indicates that synthesis methods should treat this type
as a valley.
@end deffn
@deffn GlobalConstant @code{road-x}
This constant indicates that synthesis methods should treat this type
as a road.
@end deffn
@deffn TerrainTypeProperty @code{liquid} t/f
This property is true if the terrain type represents a liquid,
which means that adjacent cells of liquid must have the same elevation.
Defaults to @code{false}.
@end deffn
@subsection Terrain Compatibility
Terrain types are not always mutually compatible.
Incompatible types may not be juxtaposed, either at
game setup time or by unit action during a game.
@deffn Table @code{adjacent-terrain-effect} t1 t2 -> t3
This table specifies what will happen to a cell of type @var{t1}
adjacent to a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
nothing will happen, otherwise it will become a cell of type @var{t3}.
If @var{t1} is a border type adjacent to a cell of type @var{t2}.
If @var{t3} is @code{non-terrain}, nothing will happen.
Otherwise, the border of type @var{t1} will be removed,
and if @var{t3} is a border type, a border of that type will be added.
The effect on connection types is analogous.
Defaults to @code{non-terrain}.
@end deffn
@subsection Other Terrain Properties
@deffn TerrainTypeProperty @code{elevation-min} dist
@end deffn
@deffn TerrainTypeProperty @code{elevation-max} dist
These properties define the minimum and maximum possible values
for the elevation in a cell of given terrain type.
Both default to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{temperature-min} n
@end deffn
@deffn TerrainTypeProperty @code{temperature-max} n
These properties define the minimum and maximum possible values
for the temperature in a cell of given terrain type.
Both default to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{wind-force-min} n
@end deffn
@deffn TerrainTypeProperty @code{wind-force-max} n
These properties define limits on wind force.
Both default to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{clouds-min} n
@end deffn
@deffn TerrainTypeProperty @code{clouds-max} n
These properties define limits on cloud density.
Both default to @code{0}.
@end deffn
@node Material Types, Type Relationships, Terrain Types, Type Definition
@section Material Types
Materials are materials that are manipulated in mass quantities.
In general, material types just index vectors of values attached
to other objects, such as unit supplies.
No more than 126 types of material may be defined.
@deffn Form @code{material-type} symbol properties@dots{}
This form defines a new type of material, named by @var{symbol}.
Details are similar to those for unit types.
@end deffn
@deffn GlobalVariable @code{m*}
This variable evaluates to a list of all material types,
listed in the same order as they were defined.
@end deffn
@deffn GlobalVariable @code{non-material}
This variable has a value that is never a material type.
@end deffn
@subsection People
A material type can be designated as representing people.
@deffn MaterialTypeProperty @code{people} n
This property is the actual number of individuals
represented by 1 of a material.
If 0, then the material type does not have people associated with it at all.
Defaults to @code{0}.
@end deffn
Multiple types of materials can represent different types of people,
so for example there could be one type @code{nomad} with 10 people/material,
and another type @code{urbanite} with 10,000 people/material.
The basic cell capacities for materials also constrain people
materials. There can be an additional limit on the number of individuals.
@deffn TerrainTypeProperty @code{people-max} n
This property is the maximum number of individuals allowed
in a cell of this type of terrain.
This is checked at the end of each turn;
any excess will be moved into adjacent cells or disappear entirely.
Defaults to @code{-1}, which allows any number of people in a cell.
@end deffn
@node Type Relationships, Hints, Material Types, Type Definition
@section Static Relationships Between Types
In general, static relationships are those that must always hold
during a turn.  @i{Xconq} will usually only test these when
necessary, but this is up to the implementation.
From the players' and designers' point of view, these relationships
can never be violated, even temporarily.
@subsection Occupants and Transports
A unit inside another unit is an ``occupant'' in a ``transport'',
even if the ``transport'' can never move.
There are two kinds of capacity.  Generic capacity is shared by
all different types, while guaranteed capacity is for a particular
type only.
@deffn UnitTypeProperty @code{capacity} n
This property is the limit on the sum of sizes of units that may occupy this
type of unit, not counting the exclusive capacities.
Defaults to @code{0}.
@end deffn
@deffn Table @code{unit-size-as-occupant} u1 u2 -> n
This table is the ``size'' of a (full-sized) unit @var{u1} when it is in
a transport @var{u2}.
Defaults to @code{1}.
@end deffn
@deffn Table @code{unit-capacity-x} u1 u2 -> n
This table is the number of units of type @var{u2} that are guaranteed
a place in a unit of type @var{u1}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{occupant-max} u1 u2 -> n
This table is the upper limit on the number of occupants of this type
(not counting @code{unit-capacity-x}).
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{occupant-total-max} n
This property is the upper limit on occupants of all types together.
Defaults to @code{-1}, which allows unlimited occupancy.
@end deffn
A unit that is an occupant may not always have the same capabilities
as when it is out in the open.  Its vision, combat, construction, and
capacity may be affected.
@deffn Table @code{occupant-vision} u1 u2 -> t/f
Defaults to @code{true}.
@end deffn
@deffn Table @code{occupant-combat} u1 u2 -> n%
This table defines the effect on the combat abilities
of a unit of type @var{u1} when an occupant in a unit of type @var{u2}.
If @code{0}, then the occupant cannot attack or fire.
Defaults to @code{100}.
@end deffn
@deffn Table @code{occupant-can-construct} u1 u2 -> t/f
This table is @code{true} if @var{u1} can
create or complete units while an occupant of @var{u2}.
Defaults to @code{false}.
@end deffn
@deffn Table @code{occupant-can-have-occupants} u1 u2 -> t/f
This table is @code{true} if @var{u1} can have occupants of its own
while an occupant of @var{u2}.
Defaults to @code{false}.
@end deffn
@subsection Units and Terrain
This section describes relationships between units and terrain.
Units can be set to disappear or be wrecked on particular types of
terrain.  If the terrain can be occupied safely, there may be a limit
on the numbers of units that can be in the same cell.
@deffn Table @code{vanishes-on} u t -> t/f
This table is @code{true} if a unit @var{u} will disappear instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn
@deffn Table @code{wrecks-on} u t -> t/f
This table is @code{true} if a unit @var{u} will wreck instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn
@deffn TerrainTypeProperty @code{capacity} n
This property is the limit on the sum of unit sizes that may share this cell.
Defaults to @code{1}.
@end deffn
@deffn Table @code{unit-size-in-terrain} u t -> n
This table is the ``size'' of a (full-sized) unit @var{u} when it is
in/on the terrain @var{t}.
Defaults to @code{1}.
@end deffn
@deffn Table @code{terrain-capacity-x} u t -> n
This table is the number of (full-sized) units of type @var{u}
that are guaranteed to have a place in the cell.
Defaults to @code{0}.
@end deffn
Note that the units' sides are irrelevant;
the sizes of units of all sides are added together.
Limits are calculated separately for the connection and open terrain
in a cell.
@deffn UnitTypeProperty @code{stack-order} n
This property is the relative position of this type of unit within a stack of
different units.
Larger values put units higher in the stack.
The exact values are unimportant, they are just used as sort keys.
The use of this value is to ensure that particular types are ``seen first''
when looking at a cell, so for instance if a truck and a city are stacked
on the same cell, everybody will see the city and not the truck.
The owner of these units can still see them.
If the stack-order of two units is the same,
then the higher-numbered type will be higher in the stack.
Defaults to @code{0}.
@end deffn
There is a possible bizarrity with stacking limits and units that can't
see each other when in the same hex, namely that a player could be prevented
from moving a unit into a cell that looks like it has enough room.
@subsection Units and Materials
Units can carry materials.  As with occupants, there is
both a generic storage space and spaces specialized for
each material type.
@deffn Table @code{unit-storage-x} u m -> n
This table is the space reserved specifically for each
type of material.
Defaults to @code{0}.
@end deffn
Materials that represent people may surrender to a unit in their cell.
@deffn Table @code{people-surrender-chance} u t -> n%
This table is the base chance that people in terrain of type @var{t}
will change sides if a unit of type @var{u} is in their cell.
Defaults to @code{0}.
@end deffn
@deffn Table @code{people-surrender-effect} u m -> n
This is a multiplier that takes the people type into account.
Defaults to @code{100}.
@end deffn
@subsection Terrain and Materials
@deffn Table @code{terrain-storage-x} t m -> n
This table is the amount of a material @var{m} that can be accumulated in a cell
with terrain @var{t}.
Defaults to @code{0}.
@end deffn
@section Vision
@deffn GlobalVariable @code{see-all} t/f
This variable is @code{true} if everything in the world, units, terrain, etc,
is always visible at all times, including initially.
It takes precedence over @i{all} other visibility and spying parameters.
Defaults to @code{false}.
@end deffn
@deffn GlobalVariable @code{see-terrain-always} t/f
If this variable is @code{true}, then any side that has seen the terrain of a cell
will be informed if that terrain ever changes.
Defaults to @code{true}.
@end deffn
@deffn UnitTypeProperty @code{see-always} t/f
This property is @code{true} when a unit is always visible
after it has been seen once,
so that side changes, movements, etc will be seen forever afterwards.
If the unit moves into terrain that has not been seen,
then that terrain also becomes seen as well.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{see-occupants} t/f
This property is @code{true} when a unit's occupants are also seen
whenever the unit itself is under observation.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{spot-action} t/f
If this property is @code{true},
then the unit's chance to be seen by other sides will be
tested each time the unit acts in any way.
This property is in addition to the check at the beginning of each turn.
Defaults to @code{true}.
@end deffn
The people in a cell effectively view (for their side)
all units in that cell.
Some units can hide from the people.
@deffn Table @code{people-see-chance} u m -> n%
This table is the chance that the people of the
given type @var{m} will see a unit of type @var{u}.
This will be evaluated for each people type individually,
once at the beginning of each turn, and once for each populated cell
that the unit enters during the turn.
Defaults to @code{100}.
@end deffn
@deffn UnitTypeProperty @code{vision-range} dist
This property is the maximum range of vision coverage by the unit.
A value of @code{-1} disables all vision,
@code{0} means only units in the same cell may be seen,
and @code{1} means units in adjacent cells may be seen.
Defaults to @code{1}.
@end deffn
@deffn Table @code{see-chance-at} u1 u2 -> n%
@end deffn
@deffn Table @code{see-chance-adjacent} u1 u2 -> n%
@end deffn
@deffn Table @code{see-chance} u1 u2 -> n%
All default to @code{100}.
@end deffn
@deffn Table @code{visibility} u t -> n
Defaults to @code{100}.
@end deffn
@deffn Table @code{vision-night-effect} u t -> n
This table is the multiplier for unit @var{u}'s vision at night
in each type of terrain @var{t}.
Effect is to multiply with both vision range and see-chance.
Defaults to @code{100}.
@end deffn
@subsection Weather Vision
@deffn GlobalVariable @code{see-weather-always} t/f
If true, then weather changes (in cells that have been seen) will always be reported.
Defaults to @code{true}.
@end deffn
@subsection Line of Sight
@deffn UnitTypeProperty @code{vision-bend} n
This property is the amount by which a unit can see ``around corners''.
0 means that vision is strictly line-of-sight,
while 100 means that elevations never obstruct vision.
Defaults to @code{100}.
@end deffn
@deffn Table @code{eye-height} u t -> dist
This propety is the additional elevation above the unit's position that a unit
can see with, when in the given terrain.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{thickness} dist
This property is the thickness of the terrain, which is the difference between
the ``ground'' of the terrain and its top.
Defaults to @code{0}.
@end deffn
@subsection Spying
A unit type can also be specified to do spying automatically.
The outcome of spying is calculated once/unit/turn,
at the beginning of the turn (after move calculation but before
any players can do anything).
Spying can happen to any unit not on the spying unit's side.
@deffn UnitTypeProperty @code{spy-chance} .01n%
This property is the chance that the unit's spies will find out something.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{spy-range} dist
This property is the maximum distance at which the unit's spies will find out
something.
Defaults to @code{0}.
@end deffn
@deffn Table @code{spy-quality} u1 u2 -> n%
This table gives the chance that @var{u1}'s spies will return information
about a unit of type @var{u2}.
Defaults to @code{100}.
@end deffn
@section Game Initialization and Naming
Game initialization always starts by resetting all the game-defining data
structures to an empty state.  This means no types, no world, etc.
Then @i{Xconq} reads and interprets
all of the game modules that have been requested.
These modules may overwrite each other arbitrarily.
Then any command line or startup options
are processed (this may involve an interactive dialog),
and the random number generator is initialized.
and players are matched with sides
(any sides needed for players will be created and named at this time).
@i{Xconq} then executes a number of @i{synthesis methods}
to do various kinds of setup.
(Some interfaces might allow for confirmation of the setup before
launching into the game proper, but this cannot be assumed.)
Since the details of good game synthesis can be complicated,
synthesis methods are simply wired-in pieces of code.
Each method is self-contained; it assumes the game state to be valid,
it will determine its own applicability and
produce a valid result.  It will also acquire any data that it
needs, so does not require any special setup;  however, a method
may fail to run if it cannot find that data.
For instance, the usual fractal
terrain generator needs percentiles for each terrain type, and
will not function without them.  It may be that all the requested
synthesis methods fail; this is OK if @i{Xconq}'s data is present
and consistent, but otherwise @i{Xconq} will shut itself down, since
it has no remaining alternatives (think of this as a serious
programming error and fix the game design).
@section The Synthesis Method List
The synthesis method list specifies which methods will be run,
and in what order.
After they have all been run, @i{Xconq} runs a consistency and completeness
check.  For instance, there should be a world with terrain everywhere.
Failure at this point is fatal; @i{Xconq} will either exit
or return to a game setup dialog.
@deffn GlobalVariable @code{synthesis-methods} method-list
This variable is a list of synthesis methods.
If the list is empty, no synthesis methods will be run.
@end deffn
The list of synthesis methods is ordered, and many contain duplicates,
so that a method can be run multiple times during setup.
Note that most of the existing methods will simply return if they
detect that their work has already been done, so multiple runs will
have no effect.
The default synthesis method list is
@example
(make-fractal-percentile-terrain
 make-countries
 make-independent-units
 make-roads
 make-rivers
 init-supplies
 name-geographical-features
@end example
The synthesis method list may also contain items of the form
@example
("program" forms...)
@end example
For each of these items, @i{Xconq} will attempt to find and run
an external program named @code{"program"},
giving it as input the result of evaluating the @code{forms},
and then reading the output of the program, which must be a valid
game module.
The program must be capable of interpreting two arguments;
the first is the name of the input file it is to read from,
and the second is the name of the output file it must write to.
If successful, it should return with a result code of 0;
otherwise, @i{Xconq} will issue a warning to players.
Any further details will depend on your system,
since each will use different conventions.
Note that this is NOT a portable construct; you cannot assume that
everybody will have built and installed the program you're using.
@subsection Fractal World
The fractal world synthesizer can make a variety of natural-looking terrain.
It relies on a number of parameters to govern a single algorithm.
@deffn SynthesisMethod @code{make-fractal-percentile-terrain}
This method generates the terrain layer of a world.
It works by generating two distinct layers of random blobs,
known as the ``alt'' and ``wet'' layers,
then decides on a terrain type for each cell.
If elevations are defined,
then this method will use the ``alt'' layer to produce elevations.
@end deffn
@deffn GlobalVariable @code{alt-blob-density} n
@end deffn
@deffn GlobalVariable @code{wet-blob-density} n
These variables are the number of blobs to put down,
expressed as number per 10,000 cells.
Defaults to @code{500}.
@end deffn
@deffn GlobalVariable @code{alt-blob-size} n.f%
@end deffn
@deffn GlobalVariable @code{wet-blob-size} n.f%
These variables are the average number of cells in a blob,
expressed as number per 10,000 cells.
Defaults to @code{100}.
@end deffn
@deffn GlobalVariable @code{alt-blob-height} n
@end deffn
@deffn GlobalVariable @code{wet-blob-height} n
These variables are the amounts by which to increment or decrement within a blob.
Defaults to @code{1000}.
@end deffn
@deffn GlobalVariable @code{alt-smoothing} n
@end deffn
@deffn GlobalVariable @code{wet-smoothing} n
These variables specify the number of averaging steps
to perform after the blobs have been generated.
Defaults to @code{2}.
@end deffn
@deffn TerrainTypeProperty @code{alt-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{alt-percentile-max} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-max} n%
These properties are
the percentiles of elevations and moistures that result in the given
terrain type.
Percentile ranges may overlap, in which case the earlier-defined
terrain type will be used.
If a cell has a alt and wet that does not fall in any of the ranges,
then terrain type 0 will be used there and players will be warned.
Mins defaults to @code{0}, maxes to @code{100}.
@end deffn
@subsection Maze World
A maze consists of a set of randomly placed ``rooms'' connected by random
passages.
@deffn SynthesisMethod @code{make-maze-terrain}
This method creates terrain that looks like a maze.
It starts by randomly assigning terrain according to its @code{occurrence},
similarly to @code{make-random-terrain} below, then carves
out rooms and passages, filling each of those with terrain
types according to their respective occurrences.
@end deffn
@deffn TerrainTypeProperty @code{maze-room-occurrence} n
This property is the weighted amount of this terrain type
in rooms in the maze.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{maze-passage-occurrence} n
This property is the weighted amount of this terrain type
in passageways in the maze.
Defaults to @code{0}.
@end deffn
@deffn GlobalVariable @code{maze-room-density} n
This variable is the fraction of the maze that is room,
expressed as the number of cells per 10,000 cells in the area.
Defaults to @code{1000}.
@end deffn
@deffn GlobalVariable @code{maze-passage-density} n
This variable is the fraction of the area that is passageway,
expressed as the number of cells per 10,000 cells in the area.
Defaults to @code{3000}.
@end deffn
@subsection Random World
The random world generator just assigns terrain and elevations randomly.
@deffn SynthesisMethod @code{make-random-terrain}
This method generates completely random terrain.
It uses a simple weighting to govern how much
of each terrain type appears, and makes random elevations as well.
@end deffn
@deffn TerrainTypeProperty @code{occurrence} n
This property is the percentage of the world that will be of this type.
Defaults to @code{1}.
@end deffn
@subsection Earthlike World
Earthlike generation uses algorithms that more closely approximate
realistic terrain.
@deffn SynthesisMethod @code{make-earthlike-terrain}
This method generates terrain that approximates what actually
appears on Earth.
@end deffn
@subsection River Generation
Rivers are borders or connections consisting of ``watery terrain''
that run downhill to regions of water.
@deffn SynthesisMethod @code{make-rivers}
This method looks for a border or connection
terrain type with a @code{subtype-x} of @code{river-x}.
then uses the world's elevation data to run rivers downhill
(always choosing the lowest of possible adjacent locations)
until they reach cell terrain with a @code{subtype} > 0.
This method will not run if there are no appropriate terrain types,
nor if there is no elevation data.
@end deffn
@deffn TerrainTypeProperty @code{river-chance} n%
This property is the chance that a river will start in or around a cell of this
terrain type.
Defaults to @code{0}.
@end deffn
@deffn GlobalVariable @code{river-sink-terrain} t
If the value of this variable is a terrain type, then a cell completely
surrounded by river will be changed to be this type.
Defaults to @code{non-terrain}.
@end deffn
Note that the algorithm computes rivers in a deterministic way,
so high values of @code{river-chance} do not result in tangled rivers.
@subsection Road Generation
The road generation method makes networks of connection terrain between
particular unit types, usually those resembling cities.
@deffn SynthesisMethod @code{make-roads}
This methods synthesizes roads for an area.
For any connection type of terrain, if no layer has been created for it
already, and the type has a @code{subtype-x} of 3,
put down roads between any pair of units whose
@code{road-chance} is nonzero.
The method will attempt to share road routes whenever possible,
and choose terrain according to @code{road-into-chance}.
@end deffn
@deffn Table @code{road-chance} u1 u2 -> n%
This table is the chance that a road will be laid, running
from a unit of type @var{u1} to one of type @var{u2}.
This is not a symmmetrical relationship.
Defaults to @code{0}.
@end deffn
@deffn Table @code{road-into-chance} t1 t2 -> n%
This table is the chance that a road will be chosen to pass
from terrain of type @var{t1} into terrain of type @var{t2}.
Defaults to @code{100}.
@end deffn
@subsection Making Countries
The @code{make-countries} method sets up the starting units for
each side, placing them in a confined area, separated from the
starting units of other sides and taking terrain preferences
into account.  If requested, this method will also expand the
country outwards by a specified amount, possibly placing additional
units in the process.
@deffn SynthesisMethod @code{make-countries}
This method works by looking for a likely place for the country,
randomly places a basic set of starting units within that area,
then expands the country outwards.
The parameters give you control over the mix of terrain types
in the country, as well as the size and relative positions of the
different countries.
This method runs on any side with fewer units than it is supposed
to start with, as given by the parameters below.
It places groups of units at locations separated from each other
by specified distances.
@end deffn
@deffn GlobalVariable @code{country-radius-min} dist
This variable is the radius of the country's initial area.
Defaults to @code{-1}, which allows the algorithm to calculate a ``reasonable''
country size appropriate to the given number of units.
@end deffn
@deffn GlobalVariable @code{country-separation-min} dist
@end deffn
@deffn GlobalVariable @code{country-separation-max} dist
These variables are the minimum and maximum
distances of country centers from each other, in cells.
If small, countries will mostly overlap;
if very large, then attempts to use small worlds will fail;
if the max and min are too close to each other, placements can also fail.
For both of these, a value of @code{-1} disables their effect.
Both default to @code{-1}.
@end deffn
The max separation bound needs to be satisfied for a country
with respect to only @i{one} other country,
so for instance the final layout may involve a long
``string'' of countries where the first and last countries are very far apart
from each other.
The minimum bound must be satisfied for all pairs of countries.
@deffn TerrainTypeProperty @code{country-terrain-min} n
This property is the minimum amount of terrain
that must be within the country's initial radius.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{country-terrain-max} n
This property is the most terrain of the given type that may appear.
If @code{-1}, then any amount may be present.
Defaults to @code{-1}.
@end deffn
@deffn UnitTypeProperty @code{start-with} n
@end deffn
@deffn UnitTypeProperty @code{independent-near-start} n
These properties set the number of units of the given type in a player's country.
These units are randomly scattered within the initial radius,
and the @code{favored} table (see below) decides which terrains
will be used.  Units may be placed inside each other; in fact,
units with no favored terrain will be made into occupants if possible.
The independent units will be placed after the ones belonging to the side,
so on the average they will get the less desirable locations in the country.
Both independent and the side's units will be named using the side's namers.
Both default to @code{0}.
@end deffn
@deffn Table @code{favored-terrain} u t -> n%
This table sets
the probability of the unit type being on the given type of terrain at the
outset.  A value of @code{0} is an absolute prohibition against placing
the unit on that type of terrain, thus every game must specify at least
one non-zero value for some terrain type and some initial unit type.
Defaults to @code{100}.
@end deffn
Once the initial country area has been set up,
then you can allow the countries to expand outwards.
Expansion occurs at the same rate for all countries.
Countries may expand into and through each other.
@deffn TerrainTypeProperty @code{country-growth-chance} n%
This property is the chance that a country will expand onto an unclaimed cell
of the given terrain type.
Defaults to @code{100}.
@end deffn
@deffn TerrainTypeProperty @code{country-takeover-chance} n%
This property is the chance that a country will expand onto another country's cell
of the given terrain type.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{unit-growth-chance} n.f%
This property is the chance that a unit of the given type will be placed
when the country expands onto a cell.
The unit will only be placed if the @code{favored} chance is also true.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{independent-growth-chance} n.f%
This property is the chance that an independent unit of the given type will be placed
when the country expands onto a cell.
The @code{favored} chance is also evaluated.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{unit-takeover-chance} n.f%
This property is the chance that a unit of the given type in another country and
belonging to another side will be given to the growing side.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{independent-takeover-chance} n.f%
This property is the chance that an independent unit of the given type in
another country will be given to the growing side.
Defaults to @code{0}.
@end deffn
@deffn GlobalVariable @code{country-radius-max} dist
This variable is a cap on the country growth process.
Values between @code{0} and @code{country-radius-min}
prevent country growth entirely,
while a value of @code{-1} allows growth to encompass the entire world.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{country-units-max} n
This property is a cap on the number of units given to the side's country.
Defaults to @code{-1}, which disables any limit.
@end deffn
@deffn GlobalVariable @code{growth-stop-chance} n%
This variable is the chance that a country's growth will stop,
if during the current [ring or round] no new cells were added
to the country.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{country-people-chance} n%
This property is the chance that the people's side will be changed to
match that for the country they are in.
Defaults to @code{100}.
@end deffn
@subsection Making Independent Units
@deffn SynthesisMethod @code{make-independent-units}
This method scatters independent units randomly
over the world.
This method will not run if the specified density of independent units
has already
been achieved, for instance from a predefined world or from country placement.
Independent units that should be inside other independents will be
handled correctly.
@end deffn
@deffn Table @code{independent-density} u t -> n
This table is the total number of independent units appearing throughout the world,
at the rate of @var{n} per 10,000 cells
of the given terrain type.
Any independent units already placed are counted first,
so this value represents final density.
If the sum of values for a given unit type on all terrain types is nonzero,
then at least one unit of that type will
be placed, even if the world is very small (i.e. the calculation of
numbers rounds up not down).
Defaults to @code{0}.
@end deffn
This method uses the @code{favored-terrain} table as the chance that a given
unit will be placed at a randomly-chosen position,
and it will keep trying different positions until a suitable one is
found.
@deffn TerrainTypeProperty @code{independent-people-chance} .01n%
This property is the chance that the people of a cell with this terrain type
will be made independent.
Deafults to @code{0}.
@end deffn
@subsection Initial Supply
By default, all units start out empty of materials.
The supply initialization method gives each unit a starting supply,
according to the stockpile tables.
@deffn SynthesisMethod @code{make-initial-materials}
This method fills unit and cell supplies to specified levels.
It will fill all units in existence at the moment it runs,
including reinforcements [and incomplete?] units.
Similarly, all cells will be filled.
@end deffn
@deffn Table @code{unit-initial-supply} u m -> n
This table is the amount of each material that each unit will start out with.
If the initial supply is greater than unit's capacity,
then the unit will just be filled to capacity.
Defaults to @code{0}.
@end deffn
@deffn Table @code{terrain-initial-supply} t m -> n
This table is the amount of material @var{m} that each cell
with terrain @var{t} will start out with.
This will be limited by the cell's capacity.
Defaults to @code{0}.
@end deffn
@subsection Naming Geographical Features
Although named geographical features don't affect the outcome of a game
in any way, they are useful for ``color'' and for identifying locations
more readably.
@deffn SynthesisMethod @code{name-geographical-features}
This method identifies and names regions as geographical features,
such as mountain ranges and islands.
@end deffn
@deffn GlobalVariable @code{feature-namers} feature-namer-list
This variable is a list of feature types and their associated namers.
This is used for features not intersecting any country
with a namer for the feature's type.
Defaults to @code{()}.
@end deffn
@deffn GlobalVariable @code{feature-types} feature-expr-list
This variable is a list of feature types that may be identified.
Examples: @code{("lake" (group (sea shallows) 1))},
@code{("peak" (high-point 1 1))}
Defaults to @code{()}.
@end deffn
@subsection Naming Units
@deffn SynthesisMethod @code{name-units-randomly}
This method gives names to previously-unnamed units,
using their usual [?] naming methods.
@end deffn
@subsection Making a Random Date
@deffn SynthesisMethod @code{make-random-date}
@end deffn
[how is this controlled?]
@section Setup Postprocessing
Some initialization steps will be done after all synthesis methods
have been run.
@i{Xconq} will always do these.
@subsection Initial View
By default, each side starts out knowing only what its units can
normally see at the beginning of the first turn.
These parameters add to that initial view.
@deffn GlobalVariable @code{terrain-seen} t/f
This variable is @code{true} if all the terrain of the world is known initially.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{initial-seen-radius} dist
This property specifies the radius of the area seen around each of
the starting units.
It computes visibility of terrain (cells and borders) only.
Defaults to @code{1} (which is a no-op if the unit's @code{vision-range}
is greater than or equal to 1).
@end deffn
@deffn UnitTypeProperty @code{already-seen} n%
This property is the chance to see units of this type at
the beginning of the game.
This applies only to units belonging to another side,
and on known terrain.
The effect is one-time, so if an @code{already-seen} unit changes
sides later on, other players will not see the change unless
they have the unit under observation for themselves.
Note that @code{see-always} implies @code{already-seen}.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{already-seen-independent} n%
This property is like @code{already-seen},
but applies to independent units specifically.
Defaults to @code{0}.
@end deffn
@node Naming, Other Parameters, Method List, Initialization
@section Naming and Text Generation
@i{Xconq} can generate names for sides, units, and geographical features.
@subsection Naming Sides
Side naming is special, because several different but related names
have to be produced.
@deffn Variable @code{side-library} side-info@dots{}
This variable is a weighted list of groups of side properties,
each of which may be used to fill in a side.
@end deffn
The form of each side name entry is basically a subset of the
side's properties:
@example
([weight] ... (name "name") ... (color-scheme "colors") ...)
@end example
Each entry can include as many or as few of the attributes as desired;
any missing will be filled in from the usual defaults.
The optional @var{weight} is a number that adjusts the probability of selection
of the given side name set; it defaults to 1, and the probability is scaled
according to the sum of the weights for all the sides listed.
If any property value is a namer, then the namer will be run.
(Note that if multiple namers are specified, they cannot be guaranteed
to coordinate with each other, so you can end up with a side noun
that is inappropriate for its corresponding side name.)
@subsection Namers
Since one of the purposes of naming is to identify objects uniquely,
any name generator should be able to maintain some memory as to
what has been generated already.
The objects that do this are @dfn{namers}.
@deffn Form @code{namer} [symbol/id] method rejects@dots{}
This form defines an instance of a namer, with either the symbolic
name or numeric id.  If either matches the name or id of an existing
namer, then the old namer will be overwritten, otherwise a new one
will be created.
The @var{method} must be one of the naming methods listed below,
and @var{rejects} defines what names may not be produced (its exact
interpretation depends on the method).
@end deffn
@subsection Naming Methods
As with general synthesis, @i{Xconq} has a number of @dfn{naming methods}
available.
An implementation is free to define additional naming methods.
@deffn NamingMethod @code{random} names...@dots{}
This method picks a name from the given list of names
and removes that name from the list
@end deffn
@deffn NamingMethod @code{junky}
This method produces a gobbledy-gook name, very techy-looking.
@end deffn
@deffn NamingMethod @code{grammar} root max-length rules@dots{}
This method defines a grammar, where @var{root} is the root symbol,
@var{max-length} is a limit on the length of the generated names
(in characters),
and @var{rules} is a list of rules of the form
@example
(@var{symbol} ([sym] [weight] @var{symbol/string/list} [n] @dots{}))
@end example
@end deffn
The generation process works by substituting one of the rule's alternatives
for the symbol, starting with the root symbol.
The probability of an alternative being selected is arrived at by
adding up the optional weights @var{weight} (assuming missing weights
to be @code{1}), and choosing with a probability of the weight
divided by the total sum of weights.
Thus the weights need not add up to any particular value.
Strings get used directly.
If a symbol in the rule's chosen expansion does not appear as the
lefthand side in any rule, then it will be handled as a string,
otherwise it will be expanded in turn.
If the symbol matches a namer's name, then that namer will be
run (passing the same object??) and its result incorporated.
A list should be a list of strings and symbols, and the expansion
of each will be concatenated.
@deffn GlobalConstant @code{any}
[???]
@end deffn
@deffn GlobalConstant @code{or}
@end deffn
@deffn GlobalConstant @code{reject}
A special rule headed by @code{reject} is a list of substrings
that should not appear in a generated name; this is a convenient
way to filter out particularly unlovely results.
@end deffn
@deffn GlobalConstant @code{capitalize}
Directs capitalization of a nonterminal.
@end deffn
[text is not actually different from a namer?]
@deffn Form @code{text} [symbol/id] method rejects@dots{}
@end deffn
[elsewhere?]
@deffn GlobalVariable @code{action-messages} patterns
@end deffn
@deffn GlobalVariable @code{event-messages} patterns
@end deffn
@node Other Parameters, New Methods, Naming, Initialization
@section Other Initialization Controls
@deffn GlobalVariable @code{edge-terrain}
This variable is the type of terrain to fill in on all the edges of a world.
The edges of a world have little or no effect on the game,
but the terrain type should be something distinctive, so that players
can recognize the edges easily.  (For instance, ice is usually a good choice
for edges, but probably not on a map of Antarctica!)
@end deffn
@section Actions in General
The parameters in this chapter define and regulate the various actions that are
available to units during a game.
Actions are always started and completed (including all of their effects)
within the same turn, and a unit can only do one of them at a time.
All actions are in theory available to all units, but the parameters
can be set so as to deny any action type to any unit type.
See the descriptions with each action type.
All action is limited by action points.
Each unit gets a certain number at the beginning of each
turn and expends them in the course of doing things.
The usual expenditure is
one point per action, but may be more, as defined for each type of action.
A unit action must always consume at least one action point.
Units can accumulate acp from turn to turn, and they can also reduce
acp below zero.
@deffn UnitTypeProperty @code{acp-per-turn} acp
This property is the basic allowance of action points that a unit gets each turn.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{acp-min} acp
This property specifies
how far into ``action debt'' a unit can go during a turn before it is prevented
entirely from acting.
A unit with acp < 1 at the beginning of a turn cannot do anything at all.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{acp-max} acp
This property is
the maximum number of action points that a unit can save up.
The value @code{-1} means that @code{acp-max} is equal to @code{acp}.
Extra acp is silently lost.
Defaults to @code{-1}.
@end deffn
@deffn UnitTypeProperty @code{free-acp} acp
This property is
the value is the amount by which the action points for some
action can exceed the unit's currently available acp
and still allow that action.
Defaults to @code{-1}, which means enough free acp to
allow any action.
@end deffn
Note that a unit with an acp of 0 is completely unintelligent, about like
a cow patty.  Cow patties can be useful for blocking paths, hiding behind,
and suchlike, and have the advantage that once they're in place, you don't
have to manage them.  Other units will have to pick them up and put them
down, of course.
@deffn Table @code{material-to-act} u m -> n
This table is a minimum amount of @var{m} needed for @var{u} to be able to act.
The material is not consumed.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{acp-damage-effect} xxx
@end deffn
@deffn Table @code{acp-night-effect} u t -> n
This table is the multiplier for unit's acp at night in each type of terrain.
Defaults to @code{100}.
@end deffn
@deffn Table @code{acp-occupant-effect} u1 u2 -> n
Defaults to @code{100}.
@end deffn
@deffn UnitTypeProperty @code{acp-per-turn-min} acp
@end deffn
@deffn UnitTypeProperty @code{acp-per-turn-max} acp
This property limits on effect of occupants, damage, etc.
Defaults to @code{1}.
@end deffn
@subsection Action Ordering
@deffn GlobalVariable @code{use-side-priority} t/f
This variable is @code{true} if the sides may only act one at a time;
otherwise, all sides and units may move simultaneously during a turn.
Defaults to @code{false}.
@end deffn
@deffn UnitTypeProperty @code{action-priority} n
This property is the order in which units of this type will act.
Higher numbers act earlier.
If the difference between the priority of one type and another
is greater than 100, then the earlier-acting units must finish acting
before the later-acting units, otherwise a player can rearrange the actual
acting order as desired.
Defaults to @code{0}.
@end deffn
@node Movement, Occupancy Parameters, Action Parameters, Unit Actions
@subsection Movement
Movement is the most common sort of action.
This section covers movement over open terrain;
the next section discusses interaction with transports.
The general theory of movement is that a unit not in a transport
crosses its current cell terrain to the edge of the cell,
crosses any border terrain, and then moves into the destination cell,
OR it moves onto connection terrain,
travels along connection terrain to the new cell, and maybe
moves off the connection.
If the unit starts in a transport, then the transport may ferry
the unit over some of the intervening terrain,
possibly as far as the unit's destination.
A unit's basic movement rate is defined by its @dfn{speed},
which is a ratio of the the unit's acp.
A speed of 100% means that the unit can potentially
enter as many cells as it has acp,
while a speed of 20% means that the unit uses at least
5 acp to enter a cell.
Movement can only succeed if several conditions are met:
the unit must be able to cross
the border terrain, the destination must be inside the world (but see below),
it must be able to exist on the terrain of the destination.
@deffn ActionType @code{move} x y z
This is the action that a unit performs to go from one location to another.
The destination must be within the @code{move-range} of the unit.
@end deffn
@deffn UnitTypeProperty @code{acp-to-move} acp
This property is the number of acp a unit uses to do one move action.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{speed} n
This property is the basic multiplier relating acp to the number
of cells that may be entered during a turn.
Defaults to @code{100}.
@end deffn
@deffn UnitTypeProperty @code{speed-damage-effect} list@dots{}
Defaults to @code{()}.
@end deffn
@deffn Table @code{speed-occupant-effect} u1 u2 -> n%
This table is the percent change in the speed
of type @var{u1} for each occupant of type @var{u2}.
If the basic speed of @var{u1} is @code{0},
then the multiplication is performed
as if the speed were @code{1} instead.
Defaults to @code{100}.
@end deffn
@deffn UnitTypeProperty @code{speed-wind-effect} xxx
@end deffn
@deffn UnitTypeProperty @code{speed-wind-angle-effect} xxx
@end deffn
@deffn UnitTypeProperty @code{speed-min} mp
This property is the worst-case speed of a unit.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{speed-max} mp
This property is the upper bound on a unit's movement in one turn.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{move-range} n
This property is the maximum distance allowed to the destination cell.
Defaults to @code{1}.
@end deffn
The product of a unit's acp and its speed is its available @dfn{movement points}.
Any move between cells will cost at least one movement point.
Some mp costs may be negative, but the total mp for a move will always
be at least 1.
@deffn Table @code{mp-to-leave-terrain} u t -> mp
This table is the mp cost to leave a cell of type @var{t}.
If @var{t} is a border type, this cost is never used.
If @var{t} is a connection type, this cost is the cost of leaving the
connection terrain for the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of leaving the cell.
Defaults to @code{0}.
@end deffn
@deffn Table @code{mp-to-enter-terrain} u t -> mp
This table is the mp cost to enter a cell of type @var{t}.
If @var{t} is a border type, this cost is the
cost of crossing the border.
If @var{t} is a connection type, this cost is the cost of entering the
connection terrain from the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of entering the cell.
Defaults to @code{1}.
@end deffn
@deffn Table @code{mp-to-traverse} u t -> mp
This table gives the cost to travel
along a connection or border of the given type.
(note that the other costs are irrelevant if
unit starts and ends its movement on the connection).
A special type of move known as a @dfn{border slide} can occur when the
endpoints of a border touch on the start and destination cells.
Sliding works like normal movement
that happens to end up on a nonadjacent cell.
Same rules for permissibility apply.
If the value is negative, then border sliding is not possible.
Defaults to @code{1}.
@end deffn
If both enter/traverse/leave and enter/leave movement is possible,
then @i{Xconq} will automatically choose the cheapest alternative.
Each unit type has a range of altitudes within which it normally operates.
@deffn Table @code{altitude-min} u t -> n
This table is the minimum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn
@deffn Table @code{altitude-max} u t -> n
This table is the maximum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{mp-to-leave-world} mp
This property is an additional move cost to leave the world entirely.
To leave, the unit must be within its @code{move-range} of an edge,
and have sufficient mp to move into the terrain in the edge cell
designated as the destination of the move.
If the value is @code{-1}, then the unit may never leave.
Defaults to @code{-1}.
@end deffn
@deffn UnitTypeProperty @code{free-mp} mp
This property is the amount by which the move points can ``go into the red''
and still allow one more move.
Defaults to @code{0}.
@end deffn
ZOC is exerted only over units out in the open, has no effect on occupants,
unless they leave their transport.
Occupants can themselves exert a ZOC,
if @code{occupant-can-fight} is true.
ZOC applies to all units on a hostile side.
@deffn Table @code{zoc-range} u1 u2 -> dist
This table is the maximum distance at which type @var{u1}
exerts a ZOC over type @var{u2}.
A value of @code{0} means that the unit controls only its own cell,
and a value of @code{-1} means that the unit does not exert a ZOC at all.
Defaults to @code{0}.
@end deffn
@deffn Table @code{zoc-into-terrain} u t -> t/f
This table is @code{true} if the unit exerts its ZOC into terrain @var{t}.
Defaults to @code{true}.
@end deffn
@deffn Table @code{zoc-from-terrain-effect} u t -> n
Defaults to @code{100}.
@end deffn
@deffn Table @code{mp-to-enter-zoc} u1 u2 -> mp
This table specifies extra movement points needed to enter the ZOC.
@code{-1} prevents entry entirely.
Defaults to @code{-1}.
@end deffn
@deffn Table @code{mp-to-leave-zoc} u1 u2 -> mp
This table specifies extra movement points needed to leave the ZOC.
@code{-1} prevents departure entirely.
Defaults to @code{0}.
@end deffn
@deffn Table @code{mp-to-traverse-zoc} u1 u2 -> mp
This table specifies extra movement points needed to move within the ZOC.
@code{-1} prevents traversing entirely.
Defaults to @code{0}.
@end deffn
If multiple units exert a ZOC into the same cell, then the mp cost
is the maximum of the different ZOC costs.
Units may use up some of their materials when they move.
Consumption happens after the move action, and only for successful moves.
@deffn Table @code{material-to-move} u m -> n
This table is the amount of each material that a unit of type @var{u}
must have in order to be able to move.
Defaults to @code{0}.
@end deffn
@deffn Table @code{consumption-per-move} u m -> n
This table is the amount of each material used by a unit to do one move action.
The amount taken is independent of terrain.
If the unit has less than the required amount of any of these materials,
it is immobilized until it gets more (this is tested before each move
action; note that this does not affect any other action, including
entering and leaving transports).
Defaults to @code{0}.
@end deffn
@node Occupancy Parameters, Tech Levels, Movement, Unit Actions
@subsection Entering and Leaving Transports
Units can be inside other units, and have units inside them, in a
tree-like fashion.  There is no limit on the depth of the tree,
but most occupant-transport relationships have other limits.
@deffn ActionType @code{enter} unit
This is the action to enter the given @var{unit}.
@end deffn
@deffn UnitTypeProperty @code{acp-to-enter-unit} acp
This property is the number of acp a unit uses to do one entry action.
Defaults to @code{1}.
@end deffn
@deffn Table @code{can-enter-independent} u1 u2 -> t/f
This table is true if a unit @var{u1} can enter an independent unit @var{u2}.
Defaults to @code{false}.
@end deffn
Entering and leaving incur mp costs as does movment,
but units with a speed of 0 may enter and leave transports.
@deffn Table @code{mp-to-enter-unit} u1 u2 -> n
This table is the extra movement points required for @var{u1}
to enter the transport @var{u2},
and vice versa (i.e. how much of transport's time is consumed by the process).
Defaults to @code{0}.
@end deffn
@deffn Table @code{mp-to-leave-unit} u1 u2 -> n
Similar to entry cost.
Defaults to @code{0}.
@end deffn
Note that these mp consumptions need not be symmetrical
between occupant and transport,
so for instance a passenger can use 2 of its mp to get on a transport,
while costing the transport only one of its mp.
@deffn Table @code{ferry-on-entry} u1 u2 -> ferry-type
@end deffn
@deffn Table @code{ferry-on-departure} u1 u2 -> ferry-type
This table specifies how much intervening terrain the unit @var{u2}
entering or leaving transport @var{u1}
will have to cross on its own (and thus incur the terrain's mp costs and
limitations).
Defaults to @code{over-border}.
@end deffn
@deffn GlobalConstant @code{over-nothing}
This constant indicates no ferrying,
occupant must pay all costs to go to destination cell.
@end deffn
@deffn GlobalConstant @code{over-own}
This constant indicates that the transport ferries over terrain
of its own cell.
@end deffn
@deffn GlobalConstant @code{over-border}
This constant indicates that the transport ferries over any
border terrain also.
@end deffn
@deffn GlobalConstant @code{over-all}
This constant indicates that the transport ferries to destination cell,
effectively putting occupant on middle of cell,
on connection terrain if necessary.
@end deffn
@subsection Research
Research is an action performed by a unit with the sole effect
of increasing its side's tech level.
Research cannot be performed by independent units.
@deffn ActionType @code{research} u
This is the action of researching the unit type @var{u}.
If the action is valid, then the tech level of the side
will increase.
Unit types with any tech crossover will also have their tech
levels adjusted.
@end deffn
@deffn UnitTypeProperty @code{acp-to-research} acp
This property is the number of action points used up by one research action.
Defaults to @code{0}, which disallows research.
@end deffn
@deffn Table @code{tech-per-research} u1 u2 -> .01n
This table is the gain in tech level resulting from a research action, expressed as
1/100 of a level.  Gains of less than 100 are probabilistic [should describe
this concept in general, used by several parms]
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{tech-per-turn-max} tl
This property is a ceiling on the total gain of tech level possible in one turn
for each side and this unit type.
Defaults to @code{9999}.
@end deffn
@subsection Tooling Up
There are several stages in the construction of a unit: tooling up,
creation, and completion.  Tooling up is where the building unit
prepares to build, creation is the step where the new unit comes into
existence, and completion is where the new unit is brought up to being
operational.
For the player, this is mostly automatic; if tooling must be
done first, a user command to build will generate the appropriate actions.
Once the technology has been achieved, a unit that intends to construct
other units may need to tool up.
This is expressed as @dfn{tool points} or @dfn{tp}.
Tool points start at zero, can be increased by tooling actions,
and may gradually decline (representing wear and tear on the equipment).
@deffn ActionType @code{toolup} u
This is the action of tooling up to build a unit of type @code{u}.
The result is an increase in the tp for the acting unit.
@end deffn
@deffn UnitTypeProperty @code{acp-to-toolup} acp
This property gives the number of acp needed to do a toolup action.
Defaults to @code{0}, which disallows tooling up.
@end deffn
@deffn Table @code{tp-per-toolup} u1 u2 -> tp
This table is the number of tp gained by one tooling action.
Defaults to @code{0}.
@end deffn
@deffn Table @code{tp-to-build} u1 u2 -> tp
This table is the number of toolup points needed before a unit of type @var{u1}
can create or build a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{tp-max} u1 u2 -> tp
This table is the maximum possible tooling.
Defaults to @code{0}.
@end deffn
@deffn Table @code{tp-attrition} u1 u2 -> tp
This table is the number of .01 tool points automatically lost at
the end of each turn.
Defaults to @code{0}.
@end deffn
@deffn Table @code{tp-crossover} u1 u2 -> n%
This table is the effective number of tool points for @var{u2} that is
guaranteed to exist, expressed as a percentage of the tool
points for @var{u1}.
[copy tech-crossover description here]
Defaults to @code{0}.
@end deffn
@subsection Creating a Unit
When a constructing unit is tooled up, the build action creates a unit
immediately and puts it in its designated location, whether inside the
unit doing the building or somewhere nearby.  This new unit, however, is
incomplete, representing the keel of the ship or the surveyor's
lines for an airstrip.  Incomplete units are thus basically skeletons,
with some unit characteristics, but unable to move or act in any way.
They also cannot have any occupants, unless the occupants are of a type
that can complete the unit.  Those occupants do not derive any protection
or other advantages from occupying the incomplete unit, and they are not
affected by the @code{occupant-can-build} limitation.
@deffn ActionType @code{create-in} u unit
This action creates a new unit of type @var{u} occupying the given
unit @var{unit}.
The unit @var{unit} must have room for the new unit.
@end deffn
@deffn ActionType @code{create-at} u x y z
This action creates a new unit of type @var{u} in the open at
@var{x,y,z}.
The cell must have room for this new unit.
@end deffn
@deffn Table @code{acp-to-create} u1 u2 -> acp
This table is the acp used by a unit of type @var{u1}
to create a a unit of type @var{u2}.
If zero, then @var{u1} cannot create a @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{create-range} u1 u2 -> dist
This table is the maximum distance at which a unit of type @var{u1}
can create a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{cp-on-creation} u1 u2 -> cp
This table is the completeness of a unit of type @var{u2} when
created by a unit of type @var{u1}.
Defaults to @code{1}.
@end deffn
@deffn Table @code{material-to-create} u m -> n
This table is the total amount of a material type @var{m}
needed to create a unit of type @var{u}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{consumption-on-creation} u m -> n
This table is the amount of a material type @var{m}
consumed to create a unit of type @var{u}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{supply-on-creation} u m -> n
This table is the amount of supply of each material type @var{m}
to give a newly created unit of type @var{u}.
This supply is newly generated, does not come from anywhere else.
(Note that players could cheat by creating units, taking their supply,
and never completing them.)
Defaults to @code{0}.
@end deffn
@subsection Building a Unit
Once an incomplete unit has been created,
other units can help to complete it.
@deffn ActionType @code{build} unit
This action adds to the completeness of @var{unit}.
If the unit becomes complete, it will be given its initial supply,
acp, name, etc.
@end deffn
@deffn Table @code{acp-to-build} u1 u2 -> acp
This table is the acp used up by one build action by a unit of type @var{u1}
when buiding a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{cp-per-build} u1 u2 -> cp
This table is the amount of completeness of a unit of type @var{u2}
added by each completion action performed by a unit of type @var{u1}.
If @code{0}, then @var{u1} cannot contribute to completing @var{u2}.
Defaults to @code{1}.
@end deffn
@deffn Table @code{material-to-build} u m -> n
This table is the amount of each material type @var{m}
that @var{u} must have in order to build anything at all.
Defaults to @code{0}.
@end deffn
@deffn Table @code{consumption-per-build} u m -> n
This table is the amount of each material type @var{m}
consumed by @var{u} when doing a build action.
Defaults to @code{0}.
@end deffn
@deffn Table @code{build-range} u1 u2 -> dist
This table is the maximum distance allowed between a unit of type @var{u1}
and the incomplete unit of type @var{u2} it is working on.
Defaults to @code{0}, which requires the two units to be in
the same cell.
@end deffn
At a given point, incomplete units can make progress towards
completion on their own.  This is automatic because incomplete
units are unable to act, and occurs at a constant specified rate.
@deffn UnitTypeProperty @code{cp-to-self-build} cp
This property is the minimum completeness of the unit necessary before it
can work on itself.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{cp-per-self-build} cp
This property is the completeness added each turn when a unit works on itself.
Defaults to @code{0}.
@end deffn
@deffn Table @code{supply-on-completion} u m -> n
This table is the minimum amount of supply of each material type @var{m}
guaranteed to a newly completed unit of type @var{u}.
If not already available to the unit, it will be newly generated.
Defaults to @code{0}.
@end deffn
@node Repair, Producing Materials, Construction, Unit Actions
@subsection Repair
Units can restore their own and each other's hp by doing repairs.
Repair requires a repair action.
The action points for this action
are taken from both the unit being repaired and
the repairer (using the same table @code{acp-to-repair}).
When a unit repairs itself, the action cost is counted once only.
@deffn ActionType @code{repair} unit
This is the action of repairing the given @var{unit}.
@end deffn
@deffn Table @code{acp-to-repair} u1 u2 -> acp
This table is the number of action points used up
by a unit of type @var{u1}
doing one repair action on a unit of type @var{u2}.
Defaults to @code{0}, which disallows the action.
@end deffn
@deffn Table @code{hp-per-repair} u1 u2 -> .01hp
This table is the hundredths of a hp that a single repair action
by a unit of type @var{u1} restores to a unit of type @var{u2}.
The fraction of this over 100 is added to hp directly,
while the < 100 fraction is added probabilistically.
(For example, a value of 160 means that 1 hp will be added for
each action, and there is a 60% chance that a second hp will
be added also.)
Defaults to @code{0}.
@end deffn
Materials may be needed and/or consumed during repair.
The materials will be taken from the
unit being repaired, then from the repairer.
@deffn Table @code{material-to-repair} u m -> .01n
This table is the amount of each material type @var{m} needed
for one repair action.
As with @code{hp-per-repair},
the < 100 part is average, and > 100 is guaranteed.
Defaults to @code{0}.
@end deffn
@deffn Table @code{consumption-per-repair} u m -> .01n
This table is the amount of each material type @var{m}
used up by a repair action.
@end deffn
The repairing unit must also not be too damaged itself to do repairs.
@deffn Table @code{hp-to-repair} u1 u2 -> hp
This table is the minimum hp level required of a unit of type @var{u1}
to repair a unit of type @var{u2}.
If less, then @var{u1} is too damaged to do any repairing.
Defaults to @code{1}, which allows repair always.
@end deffn
@node Producing Materials, Transferring Supply, Repair, Unit Actions
@subsection Producing Materials
Units can produce materials by explicit action.
@deffn ActionType @code{produce} m
This action results in a quantity of material @var{m}
coming into existence.
@end deffn
@deffn Table @code{acp-to-produce} u m -> acp
This table is the acp used up by one @code{produce} action.
Defaults to @code{0}.
@end deffn
@deffn Table @code{material-per-production} u m -> n
This table is the amount of material produced by @var{u}
when acting to produce type @var{m}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{material-to-produce} u m -> .01n
@end deffn
@node Transferring Materials, Changing Sides, Producing Materials, Unit Actions
@subsection Transferring Materials
Although most movement of materials between units happens automatically
(see backdrop economy description, section xxx),
players can also do it explicitly.
Players can both take materials from other units, and give a unit's
materials to others.
@deffn ActionType @code{transfer} unit m n
This is the action of transferring supply to the given unit @var{unit}.
The desired amount is @var{n};  if @var{m} is a valid material type,
then only that type will be transferred, otherwise the action will
transfer all types of materials possible.
The actual transfer amounts may be less than @var{n}.
[If @var{unit} is NULL, then is equiv to discarding material?]
@end deffn
@deffn Table @code{acp-to-unload} u1 m -> acp
@end deffn
@deffn Table @code{acp-to-load} u1 m -> acp
These tables are the number of action points used up by one material transfer
action from @var{u1} to @var{u2}.
The amount is independent of the material type being transferred.
If either value is @code{0}, then the material cannot be transferred.
Defaults to @code{0}.
@end deffn
@deffn Table @code{unload-max} u1 m -> n
@end deffn
@deffn Table @code{load-max} u2 m -> n
These two tables determine how much of material @var{m} can be transferred out
of a unit of type @var{u1} and into one of type @var{u2}
in one transfer action.
The actual quantity transferred by the action
is the minimum of these two values.
A value of @code{0} disallows manual transfer.
Both default to @code{-1}, which allows any amount to be transferred.
@end deffn
@node Changing Sides, Disbanding, Transferring Supply, Unit Actions
@subsection Changing Sides
@deffn ActionType @code{change-side} side
This is the action of changing the actee's side to @var{side}.
The @var{side} can be any allowable side, and the actee
may be any unit controlled by the actor's side.
@end deffn
@deffn UnitTypeProperty @code{acp-to-change-side} acp
If the value of this property is greater than 0,
then this type of unit can be ordered to change to another given side.
The type must also be allowed to be on the new side.
Defaults to @code{0}.
@end deffn
@node Disbanding, Organization, Changing Sides, Unit Actions
@subsection Disbanding
Disbanding is the voluntary and controlled destruction of a unit,
performed by the unit itself or another unit.
A disbanded unit always vanishes, rather than changing to its
@code{wrecked-type}.
@deffn ActionType @code{disband} unit
This is the action of removing hp from @var{unit}.
The unit will vanish if all its hit points are gone.
@end deffn
@deffn Table @code{acp-to-disband} u1 u2 -> acp
This table is the number of action points used by the unit @var{u1}
to do a disband action on unit @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{hp-per-disband} u1 u2 -> hp
This table is the number of hp lost in a disband action
performed by @var{u2}.
Defaults to @code{0}, which disallows disbanding.
@end deffn
A disbanded unit can be scavenged for materials.
@deffn Table @code{supply-per-disband} u m -> n%
This table is the percentage of the unit's supply that is recovered
from a single disband action.
If the value is zero, then the unit's supply will not be
recovered by the disbanding process, and be lost permanently.
If any supply remains when the unit's hp is 0, then that
supply will be lost also.
Defaults to @code{100}, which means that the entire supply
will be recovered on the first disband action.
@end deffn
Note that if an essential supply is 100% recovered before the unit
is completely disbanded, then it may die from starvation first.
A partly-disbanded unit may still acquire supply
from nearby units, via the backdrop economy.
@deffn Table @code{recycleable-material} u m -> n
This table is the quantity of each type of material that becomes available
when a unit is completely disbanded.
The materials go to transports, occupants, and nearby units, in that order.
Any materials exceeding capacities of these units will be discarded.
These materials become available only when the unit vanishes.
Defaults to @code{0}.
@end deffn
@node Organization, Combat, Disbanding, Unit Actions
@subsection Transferring Parts
Units of variable size can transfer parts of themselves to other
units, or create a new unit.
@deffn ActionType @code{transfer-part} n unit
This action moves @var{n} parts of the actee to @var{unit},
or creates a new unit if @var{unit} is omitted.
If @var{n} is negative, this takes from @var{unit} instead.
If the action takes all the parts of any involved unit,
then it vanishes.
@end deffn
@deffn UnitTypeProperty @code{acp-to-transfer-part} acp
Defaults to @code{0}.
@end deffn
@subsection Changing Type
@deffn ActionType @code{change-type} u
@end deffn
@deffn Table @code{acp-to-change-type} u1 u2 -> acp
Defaults to @code{0}.
@end deffn
@deffn Table @code{material-to-change-type} u m -> n
Defaults to @code{0}.
@end deffn
@node Combat, Detonation, Organization, Unit Actions
@subsection Combat
@i{Xconq} combat is somewhat abstract; the attacking player decides what sort
of attack to mount and perhaps when to retreat, but all else happens
automatically.
Combat may last longer than a single action;
it is then called a @dfn{battle} and divided into @dfn{rounds}.
The battle exists until one participant has a commitment of zero.
Units in a battle need not attack, and no damage will occur if none do so,
but they cannot move away until no longer committed.
The attacker/defender distinction applies only to a single action.
@deffn ActionType @code{attack} unit [commitment]
This action is a direct attack on the given @var{unit}.
The @var{unit} must be known to the attacking unit's side.
@end deffn
@deffn ActionType @code{overrun} x y z [commitment]
Overruns are a sort of combined attack/capture/move action.
The basic theory of an overrun is that the actor will attack,
capture, or co-occupy the given destination.
The exact effects depend on the types and sides of units in the destination.
@end deffn
@deffn Table @code{acp-to-attack} u1 u2 -> acp
This table is the number of action points used up by the attacker.
Defaults to @code{1}.
@end deffn
@deffn Table @code{acp-to-defend} u1 u2 -> acp
This table is the number of action points used up by the defender.
Defaults to @code{1}.
@end deffn
@deffn Table @code{attack-range-min} u1 u2 -> dist
This table is the minimum distance at which a unit can attack another.
Defaults to @code{0}.
@end deffn
@deffn Table @code{attack-range} u1 u2 -> dist
This table is the maximum distance at which a unit can attack another.
Defaults to @code{1}.
@end deffn
One round of combat consists of an attack, a reaction,
and a calculation of effects.
The defender's reaction is completely automatic, and occurs as part of the
attack action.  The defender's side does not get a chance to
decide what to do until the next round,
although doctrine can constrain the randomness somewhat.
@deffn Table @code{surrender-chance-per-attack} u1 u2 -> n%
This table is the chance that u2 will surrender to u1
immediately upon being attacked.
Defaults to @code{0}.
@end deffn
@deffn Table @code{withdraw-chance-per-attack} u1 u2 -> n%
This table is the chance that u2 will retreat from u1
immediately upon being attacked.
Defaults to @code{0}.
@end deffn
@deffn Table @code{acp-for-retreat} u1 u2 -> acp
@end deffn
In an overrun action,
if all the defending units are destroyed,
the attacker has sufficient acp and mp,
and the destination is safe to enter,
then the attacker can move into the defenders' cell.
Firing is a kind of attack that can take place at a distance,
involves no commitment or counterattack,
and for which the type of ammo may be selected.
@deffn ActionType @code{fire-at} unit [m]
This is the action of firing at a given @var{unit}.
If @var{m} is given, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn
@deffn ActionType @code{fire-into} x y [z] [m]
This is the action of firing into the cell at @var{x,y}.
If @var{z} is given, then the fire will be concentrated
on units at that elevation.
If @var{m} is given, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn
@deffn UnitTypeProperty @code{acp-to-fire} acp
If this property is greater than 0, this type may attack by firing.
Defaults to @code{0}.
@end deffn
@deffn Table @code{acp-to-be-fired-on} u1 u2 -> acp
This table is the acp lost when a unit is being fired upon.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{range} dist
This property is the maximum distance to which a unit can fire.
Defaults to @code{1}.
@end deffn
@deffn UnitTypeProperty @code{range-min} dist
This property is the minimum distance to which a unit can fire.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{elevation-at-max-range} dist
[elaborate calc to interpolate while rising and falling, basically
approximating a parabola]
@end deffn
Both attack and fire combat calculate hits and damage in the same way.
@deffn Table @code{hit-chance} u1 u2 -> n%
This table is the basic chance that a unit of type @var{u1} will
actually hit a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{attack-terrain-effect} u1 t -> n%
@end deffn
@deffn Table @code{defend-terrain-effect} u2 t -> n%
These tables specify the
effect of attacker's and defender's respective terrains on
@code{hit-chance}.
These chances are multiplied with the basic hit chance.
Default to @code{100}.
@end deffn
@deffn Table @code{hit-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on hit chance.
Its value is interpolated according to actual experience
(so that @var{n} is the effect when @var{u1} is at its maximum
experience), then multiplied with the hit chance.
Defaults to @code{100}.
@end deffn
@deffn Table @code{hit-falloff-range} u1 u2 -> n
This table is the maximum range at which the effectiveness of combat
is @i{not} affected by distance.
Defaults to @code{1}.
@end deffn
@deffn Table @code{hit-at-max-range-effect} u1 u2 -> n%
This is the multiplier for the effectiveness of combat at the
maximum range possible.
Defaults to @code{100}.
@end deffn
@deffn Table @code{damage} u1 u2 -> hp
This table is the basic amount of damage caused by a successful attack.
The value is a ``dice spec'' [explain somewhere]
Defaults to @code{1}.
@end deffn
The damage in an attack is always prorated by commitment;
the table value is for attacks at full commitment.
@deffn Table @code{damage-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on damage.
Its value is interpolated according to actual experience
(so that @var{n} is the effect when @var{u1} is at its maximum
experience), then multiplied with both the dice size and the
addend of the damage spec.
Defaults to @code{100}.
@end deffn
@deffn Table @code{hp-min} u1 u2 -> hp
This table is the lowest hp possible for @var{u1} from attacks by @var{u2}.
Further attacks by @var{u2} are still valid, but have no effect.
Defaults to @code{0}.
@end deffn
You can set a unit to use a material as ammo.
@deffn Table @code{consumption-per-attack} u1 m -> n
@end deffn
@deffn Table @code{hit-by} u2 m -> n
These tables specify material consumption in combat.
For each material @code{m}, the min of these two values is the amount
of u1's supply used up in an attack on u2.
Both default to @code{0}.
@end deffn
@deffn Table @code{material-to-fight} u m -> n
This table is a minimum of each material that is necessary to either
attack or defend.
Defaults to @code{0}.
@end deffn
Transports can protect their occupants, and vice versa.
@deffn Table @code{protection} u1 u2 -> n%
@end deffn
Transport's destruction may leave occupants stranded on hex,
will do some sort of auto-escape or die if terrain is hostile.
[use ferry-on-leave to decide]
@deffn Table @code{stack-protection} u1 u2 -> n%
@end deffn
Several other side-effects of combat may also be defined.
@deffn Table @code{retreat-chance} u1 u2 -> n%
This table is the chance that @var{u2} will retreat if hit by @var{u1}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{cxp-per-combat} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
by surviving a combat round with @var{u2}.
This applies equally to attackers and defenders.
Defaults to @code{0}.
@end deffn
@subsection Capture
Finally, a unit can attempt to capture another unit directly.
This means that the unit's side changes to that of the capturing unit.
@deffn ActionType @code{capture} unit
This is the action of capturing the given @var{unit}.
@end deffn
@deffn Table @code{acp-to-capture} u1 u2 -> acp
This table is the number of acp used up by a @code{capture} action.
Defaults to @code{0}, which disallows capture.
@end deffn
@deffn Table @code{capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{independent-capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture an independent unit
of type @var{u2}.  If the value is @code{-1}, then the chance of capture
is given by the @code{capture-chance}.
Defaults to @code{-1}.
@end deffn
@deffn Table @code{scuttle-chance} u t -> n%
This table is the chance that a unit whose capture is guaranteed will destroy
itself instead.  Scuttling is destructive, so unit changes to @code{wrecked-type}.
Occupants of an about-to-be-captured unit will also attempt to scuttle.
Defaults to @code{0}.
@end deffn
@deffn Table @code{occupant-escape-chance} u1 u2 -> n%
This table is the chance that an occupant @var{u1} will escape during the capture
of a unit of type @var{u2}.
Occupants that do not escape are either captured themselves or destroyed,
depending on their type and the capturing unit's side.
Defaults to @code{0}.
@end deffn
@deffn Table @code{hp-to-garrison} u1 u2 -> n
This table is the number of hp that will be taken from the capturing
unit @var{u1} in order to guard a captured @var{u2}.
If the amount is the unit's full hp, then the unit will vanish
and any occupants will be distributed to the captured unit, to open
terrain, or will vanish themselves if there is no other option.
Defaults to @code{0}.
@end deffn
@c @deffn Word {@var{bool unit2 unit @code{bridge}}}
@c True if the unit type @var{unit2} can be captured by another unit
@c @var{unit}, even across
@c impassable terrain.
@c @end deffn
@deffn Table @code{cxp-per-capture} u1 u2 -> ep
This table is the number of combat experience points gained by @var{u1}
by capturing @var{u2}.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{cxp-on-capture-effect} n
This property gives the change in a unit's cxp due to being captured,
expressed as a multiplier.
Defaults to @code{100}.
@end deffn
@node Detonation, Terrain Alteration, Combat, Unit Actions
@subsection Detonation
Detonation is an action and/or behavior that causes damage indiscriminately.
The action specifies the location of the detonation,
which may be in the unit's cell or an adjacent one.
A unit that detonates loses hp, changing to its @code{wrecked-type}
if it loses all of its hp.
It also hits every unit within a specified radius.
Detonation may also affect terrain within a specified radius.
@deffn ActionType @code{detonate} x y z
This action detonates the actee at the given location @var{x,y,z}.
@end deffn
@deffn UnitTypeProperty @code{acp-to-detonate} acp
This property is the number of action points used by one detonate action.
Defaults to @code{0}, which disallows detonation.
@end deffn
@deffn UnitTypeProperty @code{hp-per-detonation} hp
This property is the number of hp lost in each detonation.
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonation-unit-range} u1 u2 -> dist
This table gives the range of effect from detonation of @var{u1}.
The severity falls off according to the inverse square law
extrapolated from the adjacent cell damage.
(1/4 severity at range 2, 1/9 at 3, etc.)
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonation-damage-at} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in the same cell.
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonation-damage-adjacent} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in an adjacent cell.
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonation-terrain-range} u t -> dist
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonation-terrain-damage-chance} u t -> n%
Defaults to @code{0}.
@end deffn
@deffn Table @code{terrain-damaged-type} t1 t2 -> n
Relative chance that terrain of type @var{t1} damaged by a detonation
will change into another type @var{t2}.
Defaults to @code{0}.
@end deffn
The following tables and properties can be used for units that cannot
detonate deliberately by doing a detonate action.
@deffn Table @code{detonate-on-hit} u1 u2 -> n%
This table is the chance that a hit on @var{u1}
by a unit of type @var{u2} will cause it to detonate (once).
Noncombat reductions in hp, such as attrition, have no effect.
Defaults to @code{0}.
@end deffn
@deffn UnitTypeProperty @code{detonate-on-death} n%
This property is the chance that if this type is about to die from a combat hit,
it will detonate first.
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonate-on-capture} u1 u2 -> n%
This table is the chance that a unit of type @var{u1} will detonate if a capture
by a unit of type @var{u2} is about to succeed.
Defaults to @code{0}.
@end deffn
@deffn Table @code{detonate-on-approach-range} u1 u2 -> dist
When a unit of type @var{u2} on a non-trusted [?] side
appears at a distance of @var{dist}
or less, then @var{u1} will detonate.
If @code{-1}, then unit will not detonate upon approach.
Defaults to @code{-1}.
@end deffn
@deffn Table @code{detonation-accident-chance} u t -> n.f%
This table is the chance that the unit will detonate spontaneously.
This is checked once/turn, at the beginning of the turn, and also
upon each entry to a cell, if moving.
Defaults to @code{0}.
@end deffn
@node Terrain Alteration, Type Alteration, Detonation, Unit Actions
@subsection Altering Terrain
@deffn ActionType @code{alter-terrain} x y t
This action changes the type of the cell at @var{x,y} to @var{t}.
@end deffn
@deffn ActionType @code{add-terrain} x y dir t
This action adds a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn
@deffn ActionType @code{remove-terrain} x y dir t
This action removes a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn
@deffn Table @code{acp-to-add-terrain} u t -> n
@end deffn
@deffn Table @code{acp-to-remove-terrain} u t -> n
For auxiliary terrain types, these tables are the costs to add or remove.
For cell terrain, the costs of removing the old type and adding the
new type are added together.
@end deffn
@deffn Table @code{alter-terrain-range} u t -> n
This table is the maximum distance at which a unit can alter terrain @var{t}.
Defaults to @code{0}, which means that the unit can change only the
terrain in its own cell.
@end deffn
At present, all sides that have seen the terrain once will be informed
about any changes.
@section Environmental Computation
This section describes how to set up backdrop computations.
@subsection Random Parameters
Environmental conditions may be computed randomly.
@deffn TerrainTypeProperty @code{temperature-average} n
This property is the average temperature for each type of terrain.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{temperature-variability} n
This property is the amount of totally random variation
in the temperature in each cell.
Defaults to @code{0}.
@end deffn
@deffn TerrainTypeProperty @code{wind-force-average}
@end deffn
@deffn TerrainTypeProperty @code{wind-force-variability}
@end deffn
@deffn TerrainTypeProperty @code{wind-variability}
@end deffn
@deffn GlobalVariable @code{wind-mix-range}
This variable is the radius out to which winds interact.
If 0, then winds in adjacent cells can vary independently
of each other, and do not interact in any way.
Defaults to @code{0}.
@end deffn
@subsection Season Parameters
@deffn WorldProperty @code{year-length} n
This property is the number of turns in an annual cycle.
If less than @code{2}, then no seasonal effects will be calculated.
Defaults to @code{0}.
@end deffn
@deffn WorldProperty @code{day-length} n
This property is the number of turns in a single day.
If less than @code{2}, then day and night will not be calculated.
Defaults to @code{0}.
@end deffn
Note that @code{year-length} and @code{day-length} are
completely independent of each other, and it is possible
to have days that are longer than years.
@deffn AreaProperty @code{initial-year-part} n
This property is the season of the first turn in the game.
Defaults to @code{0}.
@end deffn
@deffn AreaProperty @code{initial-day-part} n
This property is the hour of the first turn in the game.
Defaults to @code{0}.
@end deffn
[need amount of daylight, twilight, etc]
@subsection Varying Activity with the Season
@deffn UnitTypeProperty @code{acp-season-effect} xxx
This property is the effect of the seasons on acp.
This property is added to the basic @code{acp-per-turn}.
Defaults to @code{()}.
@end deffn
@subsection Varying Temperature with the Season
@deffn GlobalVariable @code{temperature-year-cycle}
@end deffn
@deffn TerrainTypeProperty @code{temperature-moderation-range} distance
This property is the radius of the area whose raw temperatures will be averaged
to get the actual temperature.
This can be very time-consuming to calculate,
so only values of 0 (no averaging)
and 1 (average with adjacent cells) are recommended.
Defaults to @code{0}.
@end deffn
@subsection Weather Parameters
While the seasons change relatively slowly and predictably,
weather can change drastically from turn to turn.
@i{Xconq} weather is based on a daily cycle of heating and cooling
plus the movement of water vapor.
Weather and seasons can be defined completely independently of each other.
The weather model assumes a constant basic temperature, set from
summer-equator if the season model is not being used.
Atmospheric vapor is modelled by having a vapor quantity in each cell
[define a layer for this].
Vapor originates with evaporation from terrain,
moves around with changing winds and air pressure,
and high levels result in clouds, rain, and snow.
@section Environmental Effects
The environmental conditions include temperature, coatings such as snow,
and atmospheric conditions.
[specify these]
The current environmental conditions in each cell
[or in world as a whole? or calc by regions?]
derive from a combination of three calculations:
random, seasons, and weather.
@subsection Coating Effects
[effects of coating should be increased attrition, decreased
productivity, decreased activity and mobility]
@subsection Effects of Temperature on Units
Transports can protect their occupants from temperature extremes.
@deffn Table @code{temperature-protection} u1 u2 -> t/f
@end deffn
@node Economy, , Random Occurrences, Backdrop Definition
@section Economy
The following parameters control the automatic production, distribution, and
consumption of materials by units and by cells.
@subsection Unit Production and Consumption
Units can be set to always produce some amount of material without
taking explicit action.
@deffn Table @code{base-production} u m -> n
This table is the basic amount of each material @var{m}
produced by a unit of type @var{u} in each turn.
Defaults to @code{0}.
@end deffn
@deffn Table @code{occupant-base-production} u m -> n
This table is the base production of each material @var{m}
when a unit of type @var{u} is an occupant.
Defaults to @code{0}.
@end deffn
@deffn Table @code{productivity} u t -> n%
This base is the percentage productivity of a unit
of type @var{u} when on terrain of type @var{t}.
This is multiplied with the basic production rate to get actual material
production, so productivity of @code{0} completely disables production on
that terrain type, and productivity of @code{100} yields the rate
specified by @code{base-production}.
Defaults to @code{100}.
@end deffn
@deffn Table @code{productivity-min} u m -> n
@end deffn
@deffn Table @code{productivity-max} u m -> n
These tables are the
lower and upper bounds on actual production after multiplying by
productivity.
Default to @code{0} and @code{9999}, respectively.
@end deffn
@deffn Table @code{base-consumption} u m -> n
This table
sets the amount of materials consumed by the unit in a turn, even if it
doesn't move or do anything else.
Defaults to @code{0}.
@end deffn
@deffn Table @code{hp-per-starve} u m -> hp
If the unit runs out of a material that it must consume,
this table specifies how many hp it will lose each turn that it is starving.
If starving for several reasons, loss is max of starvation losses,
not the sum.
Defaults to @code{0}.
@end deffn
@deffn Table @code{consumption-as-occupant} u m -> n%
This table is the consumption by a unit of type @var{u1} when it is
an occupant of @var{u2}, expressed as a percentage
of its @code{base-consumption}.
This is useful for
units such as planes which always consume fuel in the air but not on
the ground.
Defaults to @code{100}.
@end deffn
@subsection Terrain Production and Consumption
Materials may be produced by cells, redistributed, and also taken up
by units.  Some amount of material may need to stay in the cell's storage,
or the type of terrain might change.  Exhaustion is tested after all consumption
has been accounted for.
@deffn Table @code{terrain-production} t m -> n
This table is the amount of each material @var{m} produced by a cell of the given
type @var{t} in each turn.
Defaults to @code{0}.
@end deffn
@deffn Table @code{terrain-consumption} t m -> n
This table is the amount of material @var{m} consumed by a cell of type @var{t}
each turn.
If insufficient material is available, then the terrain may change type.
Defaults to @code{0}.
@end deffn
@deffn Table @code{change-on-exhaustion-chance} t m -> n%
This table is the chance that a cell of type @var{t}, with no supply of material
of type @var{m}, will become exhausted and change to its exhausted type.
@end deffn
@deffn Table @code{terrain-exhaustion-type} t1 m -> t2
If @var{t2} is @code not {non-terrain},
then this table says that any cell with terrain @var{t1}
that is exhausted will change to @var{t2}.
If several materials are
exhausted in the same turn, then the lowest-numbered material type
will determine the new terrain type.
Defaults to @code{non-terrain}.
@end deffn
@deffn Table @code{people-consumption} m1 m2 -> n
This table is the base consumption per turn
by people of type @var{m1} of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn
@deffn Table @code{people-production} m1 m2 -> n
This table is the people of type @var{m1} base production per turn
of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn
@subsection Supply Lines
In real life, material production and consumption rarely occur in the same place
at the same time.
For some games, the player must transfer materials
manually, by loading and unloading from units.
However, this can be time-consuming and difficult,
and is best reserved for scarce and/or
valuable materials.
For more common materials, @i{Xconq} provides @dfn{supply lines}.
@deffn Table @code{in-length} u1 m -> dist
@end deffn
@deffn Table @code{out-length} u2 m -> dist
These two tables together determine the length of supply lines
between units.  The given type of material can only be transferred from
unit type @var{u1} to unit type @var{u2}
if the distance is less than the minimum of
the @code{in-length} of @var{u1} and the @code{out-length} of @var{u2}.
For instance, the @code{in-length} for a fighter's fuel might be 3 cells,
while the @code{out-length} of fuel from a city is 4 cells.
Then the fighter will be constantly supplied with fuel
when within 3 cells of a city.
If the fighter's out-length is -1, it will never
transfer any fuel to the city.
An in- or out-length of @code{0} means that the two units must be
in the same cell,
while a negative length disables the automatic transfer completely.
Long @code{out-length} lines should be used sparingly,
since the algorithm uses the @code{out-length} to
define a radius of search for units to be resupplied.
Both default to @code{0}.
@end deffn
@subsection Trade
To move materials automatically between cells,
you must define the demand and supply relationships,
as well as the rate and distance that materials can move.
Demand for a material originates with consumption and
construction needs, issuing either from a side or from
some other part of the economy.
@subsection Taxation
A side can set a taxation rate, which is the amount of material
that will be taken from the cell-based economy and given to units
on that side.
Taxes may be negative, which will have the effect of returning
materials from units back to cells.
Taxation is the last step in economic calculations.
@subsection Material Conversion
Some types of materials can be converted or combined into other types
of materials.
[do by letting production vary according to consumption?]
[in general, should distinguish productive from consumptive units,
specify as limits on in/out for each rtype]
@section Random Events
@deffn GlobalVariable @code{random-events} method-list
This variable is a list of random event methods
that will be run at the end of each turn.
The list is not ordered.
@end deffn
@subsection Terrain Attrition
Attrition is the automatic loss of hit points due to being in certain types
of terrain.
@deffn Method @code{attrition-in-terrain}
For every unit not in a transport,
this method computes the chance to lose hit points,
then damages the unit accordingly.
This method runs once per turn.
@end deffn
@deffn Table @code{attrition} u t -> .01hp
This table is the rate of loss of hp per turn.
The terrain used is cell or connection terrain as appropriate for
the unit's position.
Defaults to @code{0}.
@end deffn
@subsection Terrain Accident
Accidents result in the damage or disappearance of a unit in the open
in some kinds of terrain.
@deffn Method @code{accidents-in-terrain}
For every unit not in a transport,
this method computes the chance to be hit or to vanish completely.
This method runs once per turn.
@end deffn
@deffn Table @code{accident-hit-chance} u t -> .01n%
This table is the chance of the unit being hit while in the given terrain.
Defaults to @code{0}.
@end deffn
@deffn Table @code{accident-damage} u t -> hp
This table is the hp that will be lost in an accident.
Defaults to @code{0}.
@end deffn
@deffn Table @code{accident-vanish-chance} u t -> .01n%
This table is the chance of the unit simply vanishing while in the given terrain.
Defaults to @code{0}.
@end deffn
@subsection Revolt
Revolt is a spontaneous change of side,
occurring in place of a side-given unit action.
The new side may be none (independence) or another side.
[only if other side wants it?] [50/50 chance?]
@deffn Method @code{units-revolt}
For each completed unit, this method decides whether the unit revolts,
then changes its side.
@end deffn
@deffn UnitTypeProperty @code{revolt-chance} .01n%
This property is the chance for the unit to revolt spontaneously.
Defaults to @code{0}.
@end deffn
@subsection Surrender
@deffn Method @code{units-surrender}
For each completed unit, this method checks whether the unit will surrender
to a nearby unfriendly unit.
@end deffn
@deffn Table @code{surrender-chance} u1 u2 -> .01n%
This table is the chance that a unit of type @var{u1} will change its side
to match the side of a unit @var{u2} that is within the @code{surrender-range}
for the two types.
Defaults to @code{0}.
@end deffn
@deffn Table @code{surrender-range} u1 u2 -> dist
This table is the distance out to which a unit of type @var{u1}
will surrender to a unit of type @var{u2}.
Defaults to @code{1}.
@end deffn
@node Random State, Chrome, Populations, Miscellany
@section The Random State
It is useful to be able to restart the random number generator
consistently.
@deffn GlobalVariable @code{random-state} n
This variable is the state of the random number generator.
If this is not used, then the initial state of the random number
generator will be set in a system-dependent way.
@end deffn
@section Images and Image Families
The @code{imf} form defines graphical images in a
platform-independent way.
An @i{image family} is a named collection of images of varying
sizes and depths.
@deffn Form @code{imf} name [properties] [images]
This form declares an image family to exist, with the name @var{name}
and @var{properties}, and consisting of the specified @var{images}.
Each image has the form
@code{((@var{w} @var{h} [tile]) [@var{properties}] (@var{type} @var{data}...) ...)},
where @var{w} and @var{h} are its width and height, respectively,
the @var{type} may be one of @code{color}, @code{mono}, or @code{mask},
and the @var{data} consists of strings of hexadecimal digits.
The data strings may include slashes, which have no effect on interpretation,
but are useful to indicate each row of an image.
Color images may also have additional properties, which come between the
@var{type} and the @var{data}.
Multiple forms with the same name may occur, and each adds to the family,
overwriting individual image parts that are of the same size and depth.
@end deffn
@deffn Symbol @code{tile}
If this symbol appears following the dimensions of an image,
it indicates that the image is a pattern tile rather than a single image.
@end deffn
@deffn ImageProperty @code{actual} w h
This property is the actual size of the image data. [Ever really used?]
@end deffn
@deffn ImageProperty @code{embed} name
This property specifies that another image, similar to the image family
named by @var{name}, is already embedded within the image, and so @i{Xconq}
need not superimpose such an image itself.  This may occur when an image
has a ``builtin'' side emblem, or is readily identifiable as belonging
to a particular side, and it would be redundant for @i{Xconq} to add an
emblem when displaying a unit.
@end deffn
@deffn ImageProperty @code{embed-at} x y w h
@end deffn
@deffn ImageProperty @code{mono} data...
This property indicates that the data represents a monochrome image.
@end deffn
@deffn ImageProperty @code{mask} data...
This property indicates that the data represents a mask.
@end deffn
@deffn ImageProperty @code{color} [properties] data...
This property indicates that the data represents a color image.
@end deffn
@deffn ColorImageProperty @code{pixel-size} n
This property is the number of bits used to encode each pixel.
@end deffn
@deffn ColorImageProperty @code{row-bytes} n
This property is the number of bytes in each row of the image.
@end deffn
@deffn ColorImageProperty @code{palette} [ name | (index r g b) ... ]
This property is the color palette that should be used with the image.
@end deffn
@deffn Form @code{palette} name (index r g b) ...
This form defines a palette with the given @var{name}.
@end deffn
@deffn Form @code{color} name r g b
This form names the color.
@end deffn
Note that for the purposes of stability and change tracking,
tools that generate image families use a more restricted format.
This format requires a separate imf form for each size of image,
the size is on the same line as the imf name, and each image/mask
is on a separate line, indented by 2. (See the existing @code{lib/*.imf}
files for further detail.)
@section Default Display Style
The exact style of display depends on the user interface and
on user preferences,
but for some games, you may want to encourage a particular style
by making it be the default.
@deffn GlobalVariable @code{unseen-char} str
This variable is a string whose first character will be used to
represent unexplored terrain.
If the string consists of two characters, the second char will be
scattered throughout a field of the first char.
Defaults to @code{""}.
@end deffn
@deffn GlobalVariable @code{unseen-color} str
This variable is the name of a color that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn
@deffn GlobalVariable @code{unseen-image-name} str
This variable is the name of an image that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn
@deffn GlobalVariable @code{grid-color} str
This variable is the name of a color to use to draw the
cell-separating grid.
Defaults to @code{""}.
@end deffn
@section Dates and Time
You can make @i{Xconq} display game time as a calendar date,
rather than as a simple turn number.
@deffn GlobalVariable @code{calendar} type data@dots{}
This variable is the description of the calendar type that will be used.
If @code{none}, then turns will be reported numerically starting
from @code{1}.  If @code{usual}, then the standard Gregorian
calendar will be used.
(Other calendars may be supported in the future.)
Defaults to @code{()}, which is equivalent to @code{(number "turn")}.
For the @code{usual} calendar, the @var{data} defines how long a turn is,
in terms of the calendar.
For instance, a time measure of @code{"day"}
(and a base date of @code{"1 Jan 1900"}) will result in turns
@code{"1 Jan 1900"}, @code{"2 Jan 1900"}, etc,
while a date unit of @code{"year"}
will yield just @code{"1900"}, @code{"1901"}, and so forth.
If the numeric or @code{number} calendar is in use, then a @var{data} of @code{"day"}
will yield @code{"day 1"}, @code{"day 2"}, etc.
The rest of this variable lists the name of each season
and the turns within a year for which it is appropriate.
A twelve-turn year with four seasons could be
@example
((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn"))
@end example
If any number ranges overlap, then the first match will be used,
while if a particular turn has no named season, then it will go
unnamed in the display.
@end deffn
@deffn Symbol @code{none}
@end deffn
@deffn Symbol @code{usual}
@end deffn
@deffn GlobalVariable @code{initial-date} str
This variable is the date, in the specified calendar system, of the first turn.
Defaults to @code{""}, which has the effect of setting the initial date
to be whatever the calendar does with turn number 1.
@end deffn
@deffn GlobalVariable @code{turn} n
This variable is the number of the current turn.
Defaults to @code{0}.
@end deffn
@deffn GlobalVariable @code{last-turn} n
This variable is the number
of the last turn.
Defaults to @code{-1}, which means that there is no limit on the number
of turns.
@end deffn
@deffn GlobalVariable @code{extra-turn-chance} n%
This variable is the chance that the game will go one more turn
after the @code{last-turn}.
@end deffn
@i{Xconq} is currently limited to games of 32,767 turns.
@subsection Real Time
A game may also be limited in real time.
@deffn GlobalVariable @code{real-time-for-game} seconds
@end deffn
@deffn GlobalVariable @code{real-time-per-turn} seconds
@end deffn
@deffn GlobalVariable @code{real-time-per-side} seconds
@end deffn
@deffn GlobalVariable @code{elapsed-real-time} seconds
This is the difference in real time between the start of the game
and its current state.
@end deffn
@section Miscellany
GDL forms in this section are those that do not seem to fit anywhere
else.
@deffn UnitTypeProperty @code{name-internal} str
Internally used type name.
@end deffn
@subsection Debugging
@deffn Form @code{print} value
This form prints to a console (or whatever the interface provides)
the object @var{value}, in GDL syntax.
@end deffn
@subsection Internal AI Data
These are normally computed and used internally by AIs.
They can be filled in by a game design, but the effects
are undocumented and will depend on the working of the AI
using these forms.
@deffn XXX @code{zz-fr}
@end deffn
@deffn XXX @code{zz-b}
@end deffn
@deffn XXX @code{zz-bb}
@end deffn
@deffn XXX @code{zz-transport}
@end deffn
@deffn XXX @code{zz-c}
@end deffn
@deffn XXX @code{zz-cm}
@end deffn
@deffn XXX @code{zz-cc}
@end deffn
@deffn XXX @code{zz-bw}
@end deffn
@deffn Table @code{zz-basic-hit-worth}
@end deffn
@deffn Table @code{zz-basic-capture-worth}
@end deffn
@deffn Table @code{zz-basic-transport-worth}
@end deffn